sevenx_engine 0.2.11

# 📖 API 3D Completa - SevenX Engine v0.2.9


## 🎯 Índice


1. [Vec3 - Vetores 3D](#vec3---vetores-3d)
2. [Mesh3D - Geometria](#mesh3d---geometria)
3. [Camera3D - Câmera](#camera3d---câmera)
4. [Renderer3D - Renderização](#renderer3d---renderização)
5. [Shaders 3D](#shaders-3d)
6. [Partículas 3D](#partículas-3d)
7. [Model Loader](#model-loader)
8. [Iluminação](#iluminação)
9. [PBR (Physically Based Rendering)](#pbr)
10. [Otimizações 3D](#otimizações-3d)

---

## Vec3 - Vetores 3D


### Criar Vetor


```rust
use sevenx_engine::Vec3;

// Novo vetor
let v = Vec3::new(1.0, 2.0, 3.0);

// Vetor zero
let zero = Vec3::zero();

// Vetor unitário
let up = Vec3::up();      // (0, 1, 0)
let down = Vec3::down();  // (0, -1, 0)
let left = Vec3::left();  // (-1, 0, 0)
let right = Vec3::right();// (1, 0, 0)
let forward = Vec3::forward();  // (0, 0, -1)
let back = Vec3::back();        // (0, 0, 1)
```

### Operações Matemáticas


```rust
// Adição
let v3 = v1 + v2;
v1 += v2;

// Subtração
let v3 = v1 - v2;
v1 -= v2;

// Multiplicação por escalar
let v2 = v1 * 2.0;
v1 *= 2.0;

// Divisão por escalar
let v2 = v1 / 2.0;
v1 /= 2.0;

// Negação
let v2 = -v1;
```

### Métodos


```rust
// Comprimento
let len = v.length();
let len_sq = v.length_squared();

// Normalizar (vetor unitário)
let normalized = v.normalize();
v.normalize_mut();  // In-place

// Produto escalar (dot product)
let dot = v1.dot(&v2);

// Produto vetorial (cross product)
let cross = v1.cross(&v2);

// Distância entre pontos
let dist = v1.distance(&v2);
let dist_sq = v1.distance_squared(&v2);

// Interpolação linear
let lerp = v1.lerp(&v2, 0.5);  // 50% entre v1 e v2

// Reflexão
let reflected = v.reflect(&normal);

// Projeção
let projected = v.project(&onto);
```

---

## Mesh3D - Geometria


### Primitivas


```rust
use sevenx_engine::Mesh3D;

// Cubo
let cube = Mesh3D::cube(size);

// Esfera
let sphere = Mesh3D::sphere(radius, segments);

// Cilindro
let cylinder = Mesh3D::cylinder(radius, height, segments);

// Cone
let cone = Mesh3D::cone(radius, height, segments);

// Pirâmide
let pyramid = Mesh3D::pyramid(base_size, height);

// Cápsula
let capsule = Mesh3D::capsule(radius, height, segments);

// Torus (rosquinha)
let torus = Mesh3D::torus(major_radius, minor_radius, major_segments, minor_segments);

// Icosfera (esfera mais uniforme)
let icosphere = Mesh3D::icosphere(radius, subdivisions);

// Prisma
let prism = Mesh3D::prism(sides, radius, height);

// Plano
let plane = Mesh3D::plane(width, depth);

// Quad (retângulo 3D)
let quad = Mesh3D::quad(width, height);

// Grade
let grid = Mesh3D::grid(width, depth, width_segments, depth_segments);
```

### Primitivas Dimensionadas


```rust
// Caixa com dimensões específicas
let box_mesh = Mesh3D::box_sized(width, height, depth);

// Cilindro com raios diferentes
let cylinder = Mesh3D::cylinder_sized(radius_top, radius_bottom, height, segments);

// Esfera com escala não-uniforme
let sphere = Mesh3D::sphere_sized(radius_x, radius_y, radius_z, segments);
```

### Primitivas Especiais


```rust
// Anel
let ring = Mesh3D::ring(inner_radius, outer_radius, segments);

// Estrela
let star = Mesh3D::star(points, inner_radius, outer_radius, height);
```

### Transformações


```rust
// Posição
mesh.position = Vec3::new(x, y, z);
mesh.translate(Vec3::new(dx, dy, dz));

// Rotação (radianos)
mesh.rotation = Vec3::new(rx, ry, rz);
mesh.rotate_x(angle);
mesh.rotate_y(angle);
mesh.rotate_z(angle);

// Escala
mesh.scale = Vec3::new(sx, sy, sz);
mesh.scale(Vec3::new(sx, sy, sz));
mesh.scale_uniform(s);  // Escala uniforme
```

### Cor e Material


```rust
// Definir cor
mesh.set_color([r, g, b, a]);  // 0-255

// Cor por vértice
for vertex in &mut mesh.vertices {
    vertex.color = [255, 0, 0, 255];
}
```

### Manipulação de Geometria


```rust
// Calcular normais
mesh.calculate_normals();

// Suavizar normais
mesh.smooth_normals();

// Inverter normais
mesh.flip_normals();

// Mesclar meshes
mesh1.merge(&mesh2);

// Subdividir
mesh.subdivide();

// Espelhar
let mirrored = mesh.mirror(MirrorAxis::X);

// Bounding box
let (min, max) = mesh.get_bounding_box();
let center = mesh.get_center();
let size = mesh.get_size();
```

### Informações


```rust
// Contagem
let vertex_count = mesh.vertices.len();
let triangle_count = mesh.indices.len() / 3;

// Propriedades
let area = mesh.surface_area();
let volume = mesh.volume();
```

---

## Camera3D - Câmera


### Criar Câmera


```rust
use sevenx_engine::Camera3D;

let mut camera = Camera3D::new(width, height);
```

### Posição e Orientação


```rust
// Posição
camera.position = Vec3::new(0.0, 2.0, 5.0);

// Rotação (radianos)
camera.rotation = Vec3::new(pitch, yaw, roll);

// Olhar para ponto
camera.look_at(Vec3::new(0.0, 0.0, 0.0));

// Direções
let forward = camera.get_forward();
let right = camera.get_right();
let up = camera.get_up();
```

### Movimento


```rust
// Mover para frente/trás
camera.move_forward(distance);
camera.move_backward(distance);

// Mover para lados
camera.move_left(distance);
camera.move_right(distance);

// Mover para cima/baixo
camera.move_up(distance);
camera.move_down(distance);

// Rotacionar
camera.rotate(pitch, yaw, roll);
camera.rotate_around_target(yaw, pitch);
```

### Projeção


```rust
// Configurar projeção
camera.fov = 60.0;      // Field of view (graus)
camera.near = 0.1;      // Plano próximo
camera.far = 100.0;     // Plano distante
camera.aspect = 16.0 / 9.0;  // Aspect ratio

// Projetar ponto 3D para 2D
if let Some((screen_x, screen_y)) = camera.project(&point, width, height) {
    // Ponto visível na tela
}
```

### Matrizes


```rust
// Obter matrizes
let view_matrix = camera.get_view_matrix();
let projection_matrix = camera.get_projection_matrix();
let vp_matrix = camera.get_view_projection_matrix();
```

---

## Renderer3D - Renderização


### Criar Renderer


```rust
use sevenx_engine::Renderer3D;

let mut renderer = Renderer3D::new(width, height);
```

### Configurações


```rust
// Wireframe
renderer.wireframe = true;

// Backface culling
renderer.backface_culling = true;

// Cor de fundo
renderer.clear_color = [20, 20, 30, 255];
```

### Renderizar


```rust
// Limpar zbuffer
for z in &mut renderer.zbuffer {
    *z = f32::INFINITY;
}

// Renderizar mesh
renderer.render_mesh(&mesh, &camera, pixels, width, height);
```

### Estatísticas


```rust
let stats = renderer.get_stats();
println!("Triângulos: {}", stats.triangles_rendered);
println!("Culled: {}", stats.triangles_culled);
```

---

## Shaders 3D


### Phong Shader (Iluminação)


```rust
use sevenx_engine::{PhongShader, Light3D, Material};

let mut phong = PhongShader::new();
phong.ambient_light = [0.1, 0.1, 0.1];

// Adicionar luz
phong.add_light(Light3D::new(
    Vec3::new(5.0, 10.0, 5.0),  // Posição
    [1.0, 1.0, 1.0],             // Cor RGB (0-1)
    1.5                          // Intensidade
));

// Material
let material = Material {
    ambient: [0.2, 0.2, 0.2],
    diffuse: [0.8, 0.8, 0.8],
    specular: [1.0, 1.0, 1.0],
    shininess: 32.0,
};

// Calcular iluminação
let color = phong.calculate_lighting(
    &position,
    &normal,
    &view_dir,
    &material,
    base_color
);
```

### Toon Shader (Cel Shading)


```rust
use sevenx_engine::ToonShader;

let toon = ToonShader::new(4)  // 4 níveis de cor
    .with_outline(0.1, [0, 0, 0, 255]);

let color = toon.apply(base_color, light_intensity);

if toon.should_outline(normal_dot_view) {
    // Desenhar contorno
}
```

### Fresnel Shader (Rim Lighting)


```rust
use sevenx_engine::FresnelShader;

let fresnel = FresnelShader::new();
let color = fresnel.calculate(&normal, &view_dir, base_color);
```

### Fog Shader (Neblina)


```rust
use sevenx_engine::FogShader;

let mut fog = FogShader::new();
fog.fog_color = [200, 200, 220, 255];
fog.fog_density = 0.05;
fog.fog_start = 10.0;
fog.fog_end = 50.0;

let color = fog.apply(base_color, distance);
```

### Normal Map Shader


```rust
use sevenx_engine::NormalMapShader;

let normal_map = NormalMapShader::new(0.5);  // Força
let perturbed_normal = normal_map.perturb_normal(&normal, u, v);
```

### Reflection Shader


```rust
use sevenx_engine::ReflectionShader;

let mut reflection = ReflectionShader::new();
reflection.reflectivity = 0.5;
reflection.environment_color = [0.5, 0.7, 1.0];

let color = reflection.calculate(&normal, &view_dir, base_color);
```

### Wireframe Shader


```rust
use sevenx_engine::WireframeShader;

let wireframe = WireframeShader::new()
    .with_colors(
        [255, 255, 255, 255],  // Linhas
        [50, 50, 50, 255]      // Preenchimento
    )
    .with_line_width(2.0);
```

---

## Partículas 3D


### Criar Sistema


```rust
use sevenx_engine::{ParticleSystem3D, Particle3D};

let mut particles = ParticleSystem3D::new(500);
particles.gravity = Vec3::new(0.0, -9.8, 0.0);
```

### Efeitos Pré-configurados


```rust
let position = Vec3::new(0.0, 0.0, 0.0);

// Explosão
particles.explosion(position);

// Fogo
particles.fire(position);

// Magia
particles.magic(position);

// Fumaça
particles.smoke(position);

// Faíscas
particles.sparkles(position);

// Rastro
let direction = Vec3::new(1.0, 0.0, 0.0);
particles.trail(position, direction);
```

### Partícula Customizada


```rust
let particle = Particle3D::new(
    Vec3::new(0.0, 0.0, 0.0),      // Posição
    Vec3::new(1.0, 2.0, 0.5),      // Velocidade
    [255, 100, 50, 255],           // Cor
    2.0,                            // Vida
)
.with_acceleration(Vec3::new(0.0, -5.0, 0.0))
.with_rotation(0.0, 5.0)
.with_scale(1.0, -0.3)
.with_color_shift([-80.0, -50.0, 0.0, 0.0])
.with_turbulence(0.2);

particles.particles.push(particle);
```

### Atualizar


```rust
// No update
particles.update(dt);

// Limpar
particles.clear();
```

---

## Model Loader


### Carregar Modelo


```rust
use sevenx_engine::ModelLoader;

// Carregar OBJ
let mesh = ModelLoader::load_obj("assets/model.obj")?;

// Carregar com materiais
let (mesh, materials) = ModelLoader::load_obj_with_materials("assets/model.obj")?;
```

### Model Builder


```rust
use sevenx_engine::ModelBuilder;

let mesh = ModelBuilder::new()
    .add_vertex(Vec3::new(0.0, 0.0, 0.0))
    .add_vertex(Vec3::new(1.0, 0.0, 0.0))
    .add_vertex(Vec3::new(0.0, 1.0, 0.0))
    .add_triangle(0, 1, 2)
    .with_color([255, 0, 0, 255])
    .build();
```

---

## Iluminação


### Tipos de Luz


```rust
use sevenx_engine::Light3D;

// Luz pontual
let point = Light3D::point(x, y, z)
    .with_color(r, g, b)
    .with_intensity(intensity)
    .with_radius(radius);

// Luz direcional (sol)
let sun = Light3D::directional(dx, dy, dz)
    .with_color(r, g, b)
    .with_intensity(intensity);

// Luz spot (lanterna)
let spot = Light3D::spot(x, y, z, dx, dy, dz)
    .with_color(r, g, b)
    .with_intensity(intensity)
    .with_angle(angle_degrees)
    .with_radius(radius);
```

### Sistema de Iluminação


```rust
use sevenx_engine::LightingSystem;

let mut lighting = LightingSystem::new();

// Luz ambiente
lighting.set_ambient(r, g, b, intensity);

// Adicionar luzes
let light_id = lighting.add_light(light);
lighting.remove_light(light_id);

// Aplicar iluminação
let lit_color = lighting.apply_lighting(position, normal, view_dir, material);
```

---

## PBR


### PBR Material


```rust
use sevenx_engine::PBRMaterial;

// Materiais pré-definidos
let gold = PBRMaterial::gold();
let silver = PBRMaterial::silver();
let copper = PBRMaterial::copper();
let iron = PBRMaterial::iron();
let aluminum = PBRMaterial::aluminum();
let plastic = PBRMaterial::plastic();
let rubber = PBRMaterial::rubber();
let glass = PBRMaterial::glass();
let wood = PBRMaterial::wood();
let stone = PBRMaterial::stone();

// Material customizado
let material = PBRMaterial::new()
    .color(0.8, 0.2, 0.2)      // Albedo RGB (0-1)
    .metal(1.0)                 // Metallic (0-1)
    .rough(0.3)                 // Roughness (0-1)
    .ao(1.0)                    // Ambient Occlusion
    .emissive(0.0, 0.0, 0.0, 0.0);  // Emissão (RGB + intensidade)
```

### PBR Shader


```rust
use sevenx_engine::PBRShader;

let mut pbr = PBRShader::new();

// Adicionar luzes
pbr.add_light(PBRLight::point(5.0, 5.0, 5.0)
    .with_color(1.0, 1.0, 1.0)
    .with_intensity(10.0));

// Calcular iluminação PBR
let color = pbr.shade(&material, &position, &normal, &view_dir);
```

### PBR Light


```rust
use sevenx_engine::PBRLight;

// Luz pontual
let light = PBRLight::point(x, y, z)
    .with_color(r, g, b)
    .with_intensity(intensity);

// Luz direcional
let sun = PBRLight::directional(dx, dy, dz)
    .with_color(r, g, b)
    .with_intensity(intensity);

// Luz spot
let spot = PBRLight::spot(x, y, z, dx, dy, dz)
    .with_color(r, g, b)
    .with_intensity(intensity)
    .with_angle(angle);
```

### Advanced Renderer 3D (⚠️ Bug na v0.2.9)


```rust
use sevenx_engine::{AdvancedRenderer3D, RenderQuality};

let mut renderer = AdvancedRenderer3D::new(width, height);
renderer.set_quality(RenderQuality::High);

// Configurações
renderer.shadow_map.enabled = true;
renderer.ssao.enabled = true;
renderer.hdr.enabled = true;
renderer.bloom.enabled = true;

// Renderizar (⚠️ Tem bug na v0.2.9)
// Use Renderer3D básico por enquanto
```

---

## Otimizações 3D


### Frustum Culling


```rust
use sevenx_engine::{Frustum, BoundingSphere};

let frustum = Frustum::from_camera(&camera, aspect_ratio);

let sphere = BoundingSphere::new(mesh.position, radius);
if frustum.contains_sphere(&sphere) {
    // Renderizar apenas se visível
    renderer.render_mesh(&mesh, &camera, pixels, width, height);
}
```

### LOD (Level of Detail)


```rust
use sevenx_engine::LODMesh;

let base_mesh = Mesh3D::sphere(2.0, 32);
let mut lod_mesh = LODMesh::new(base_mesh);

// No update
lod_mesh.update(camera.position, object_position);

// Pegar mesh otimizada
let mesh = lod_mesh.get_current_mesh();
```

### Octree


```rust
use sevenx_engine::{Octree, BoundingBox};

let bounds = BoundingBox::new(
    Vec3::new(-50.0, -50.0, -50.0),
    Vec3::new(50.0, 50.0, 50.0)
);

let mut octree = Octree::new(bounds, 4, 8);

// Inserir objetos
octree.insert(position, object_id);

// Buscar objetos próximos
let nearby = octree.query_sphere(center, radius);
```

### Skybox


```rust
use sevenx_engine::Skybox;

// Presets
let skybox = Skybox::day_sky();
let skybox = Skybox::night_sky();
let skybox = Skybox::sunset_sky();

// Customizado
let mut skybox = Skybox::new([
    top_color,
    bottom_color,
    north_color,
    south_color,
    east_color,
    west_color,
]);

// Atualizar
skybox.update(dt);
```

### Terreno


```rust
use sevenx_engine::{Terrain, TerrainConfig};

// Presets
let terrain = Terrain::flat(50, 50);
let terrain = Terrain::hills(50, 50, 15.0);
let terrain = Terrain::mountains(100, 100, 30.0);

// Customizado
let config = TerrainConfig {
    width: 100,
    depth: 100,
    height_scale: 20.0,
    octaves: 6,
    persistence: 0.5,
    lacunarity: 2.0,
    seed: 42,
};
let terrain = Terrain::new(config);

// Obter altura
let height = terrain.get_height_at(x, z);
```

### Billboards


```rust
use sevenx_engine::{Billboard, BillboardBatch, BillboardType};

let mut billboards = BillboardBatch::new();

// Billboard esférico (sempre olha para câmera)
billboards.add(
    Billboard::spherical(position, width, height)
        .with_color([50, 150, 50, 255])
);

// Billboard cilíndrico (só rotaciona em Y)
billboards.add(
    Billboard::cylindrical(position, width, height)
        .with_texture("tree.png".to_string())
);

// Ordenar por distância
billboards.sort_by_distance(camera.position);

// Converter para meshes
let meshes = billboards.to_meshes(&camera);
```

---

## Exemplo Completo 3D


```rust
use sevenx_engine::*;

struct Game3D {
    renderer: Renderer3D,
    camera: Camera3D,
    cube: Mesh3D,
    sphere: Mesh3D,
    time: f32,
}

impl GameState for Game3D {
    fn new() -> Self {
        let renderer = Renderer3D::new(800, 600);
        
        let mut camera = Camera3D::new(800, 600);
        camera.position = Vec3::new(0.0, 2.0, 5.0);
        camera.look_at(Vec3::zero());
        
        let mut cube = Mesh3D::cube(1.0);
        cube.position = Vec3::new(-2.0, 0.0, 0.0);
        cube.set_color([255, 100, 100, 255]);
        
        let mut sphere = Mesh3D::sphere(1.0, 16);
        sphere.position = Vec3::new(2.0, 0.0, 0.0);
        sphere.set_color([100, 100, 255, 255]);
        
        Self {
            renderer,
            camera,
            cube,
            sphere,
            time: 0.0,
        }
    }
    
    fn update(&mut self, dt: f32, input: &input::InputHandler, _world: &mut world::World) {
        self.time += dt;
        
        // Rotacionar objetos
        self.cube.rotation.y = self.time;
        self.sphere.rotation.x = self.time * 0.5;
        
        // Câmera orbital
        let radius = 5.0;
        self.camera.position.x = self.time.cos() * radius;
        self.camera.position.z = self.time.sin() * radius;
        self.camera.look_at(Vec3::zero());
    }
    
    fn draw(&mut self, _world: &world::World, pixels: &mut [u8]) {
        // Limpar tela
        for pixel in pixels.chunks_exact_mut(4) {
            pixel.copy_from_slice(&[20, 20, 30, 255]);
        }
        
        // Limpar zbuffer
        for z in &mut self.renderer.zbuffer {
            *z = f32::INFINITY;
        }
        
        // Atualizar câmera do renderer
        self.renderer.camera = self.camera.clone();
        
        // Renderizar
        self.renderer.render_mesh(&self.cube, pixels, 800, 600);
        self.renderer.render_mesh(&self.sphere, pixels, 800, 600);
        
        // HUD
        ui::render_text(
            "SevenX Engine - 3D Demo",
            10, 10,
            [255, 255, 255, 255],
            pixels,
            800
        );
    }
}

fn main() {
    let config = config::EngineConfig::new()
        .with_title("3D Game")
        .with_size(800, 600);
    
    Engine::with_config(config).run::<Game3D>();
}
```

---

**API 3D Completa! 🎮🎨**