# 🎨 Guia de Primitivas 2D e 3D - SevenX Engine v0.2.6
## ✨ Novidades v0.2.6
**Adicionado:**
- ✅ 7 novas primitivas 3D (Cone, Capsule, Quad, Torus, Grid, Icosphere, Prism)
- ✅ 4 métodos auxiliares 3D (set_color, calculate_normals, merge, flip_normals)
- ✅ Sistema completo de primitivas 2D com 20+ métodos
- ✅ 2 exemplos interativos (primitives_3d_showcase, primitives_2d_showcase)
**Comandos:**
```bash
cargo run --example primitives_3d_showcase # Showcase 3D
cargo run --example primitives_2d_showcase # Showcase 2D
```
---
## 📦 Primitivas 3D
O SevenX Engine oferece 12 primitivas 3D prontas para uso:
### Básicas
#### 1. **Cube** (Cubo)
```rust
let cube = Mesh3D::cube(2.0); // tamanho
```
- 6 faces quadradas
- Ideal para: blocos, caixas, construções
#### 2. **Sphere** (Esfera UV)
```rust
let sphere = Mesh3D::sphere(1.0, 16); // raio, segmentos
```
- Gerada por coordenadas UV
- Ideal para: planetas, bolas, objetos redondos
#### 3. **Cylinder** (Cilindro)
```rust
let cylinder = Mesh3D::cylinder(0.5, 2.0, 16); // raio, altura, segmentos
```
- Faces laterais suaves
- Ideal para: colunas, tubos, troncos de árvore
#### 4. **Cone** (Cone)
```rust
let cone = Mesh3D::cone(1.0, 2.0, 16); // raio, altura, segmentos
```
- Base circular com ponta
- Ideal para: árvores, foguetes, chapéus
#### 5. **Pyramid** (Pirâmide)
```rust
let pyramid = Mesh3D::pyramid(1.5); // tamanho
```
- Base quadrada com 4 faces triangulares
- Ideal para: construções, monumentos
### Avançadas
#### 6. **Capsule** (Cápsula)
```rust
let capsule = Mesh3D::capsule(0.5, 2.0, 16); // raio, altura, segmentos
```
- Cilindro com pontas arredondadas
- Ideal para: personagens, colisões, pílulas
#### 7. **Torus** (Rosquinha)
```rust
let torus = Mesh3D::torus(1.0, 0.3, 16, 12); // raio maior, raio menor, segmentos maiores, segmentos menores
```
- Forma de anel/rosquinha
- Ideal para: anéis, pneus, decorações
#### 8. **Icosphere** (Esfera Icosaédrica)
```rust
let icosphere = Mesh3D::icosphere(1.0, 2); // raio, subdivisões (0-2)
```
- Esfera mais uniforme que a UV
- Ideal para: objetos que precisam de geometria uniforme
#### 9. **Prism** (Prisma)
```rust
let prism = Mesh3D::prism(1.0, 2.0, 6); // raio, altura, lados
```
- Polígono regular extrudado
- Ideal para: arquitetura, cristais, formas geométricas
### Utilitárias
#### 10. **Plane** (Plano Horizontal)
```rust
let plane = Mesh3D::plane(10.0, 10.0); // largura, profundidade
```
- Superfície plana horizontal
- Ideal para: chão, teto, superfícies
#### 11. **Quad** (Plano Vertical)
```rust
let quad = Mesh3D::quad(2.0, 2.0); // largura, altura
```
- Superfície plana vertical
- Ideal para: billboards, sprites 3D, placas
#### 12. **Grid** (Malha)
```rust
let grid = Mesh3D::grid(20.0, 20.0, 20, 20); // largura, profundidade, divisões X, divisões Z
```
- Malha subdividida
- Ideal para: terreno, debug, visualização
## 🎨 Métodos Auxiliares de Mesh3D
### Manipulação de Cor
```rust
mesh.set_color([255, 0, 0, 255]); // Define cor de todos os vértices
```
### Cálculo de Normais
```rust
mesh.calculate_normals(); // Recalcula normais (flat shading)
```
### Combinação de Meshes
```rust
mesh1.merge(&mesh2); // Combina duas meshes em uma
```
### Inversão de Normais
```rust
mesh.flip_normals(); // Inverte normais (útil para objetos internos)
```
## 🖌️ Primitivas 2D
O novo sistema `Primitives2D` oferece renderização direta de formas 2D:
### Básicas
#### Pixel
```rust
prims.draw_pixel(x, y, [255, 0, 0, 255]);
```
#### Linha
```rust
prims.draw_line(x0, y0, x1, y1, color);
prims.draw_thick_line(x0, y0, x1, y1, thickness, color);
```
#### Retângulo
```rust
prims.draw_rect(x, y, width, height, color); // Contorno
prims.draw_rect_filled(x, y, width, height, color); // Preenchido
```
#### Círculo
```rust
prims.draw_circle(cx, cy, radius, color); // Contorno
prims.draw_circle_filled(cx, cy, radius, color); // Preenchido
```
#### Elipse
```rust
prims.draw_ellipse(cx, cy, rx, ry, color);
```
### Polígonos
#### Triângulo
```rust
prims.draw_triangle(x0, y0, x1, y1, x2, y2, color); // Contorno
prims.draw_triangle_filled(x0, y0, x1, y1, x2, y2, color); // Preenchido
```
#### Polígono
```rust
let points = vec![(x0, y0), (x1, y1), (x2, y2), ...];
prims.draw_polygon(&points, color);
```
### Avançadas
#### Arco
```rust
use std::f32::consts::PI;
prims.draw_arc(cx, cy, radius, start_angle, end_angle, color);
// Exemplo: semicírculo
prims.draw_arc(100, 100, 50, 0.0, PI, [255, 0, 0, 255]);
```
#### Grade
```rust
prims.draw_grid(cell_size, color);
```
#### Flood Fill
```rust
prims.flood_fill(x, y, target_color, fill_color);
```
### Gradientes
#### Gradiente Horizontal
```rust
prims.draw_gradient_h(x, y, width, height, color1, color2);
```
#### Gradiente Vertical
```rust
prims.draw_gradient_v(x, y, width, height, color1, color2);
```
#### Gradiente Radial
```rust
prims.draw_gradient_radial(cx, cy, radius, color1, color2);
```
## 📝 Exemplo de Uso - 3D
```rust
use sevenx_engine::*;
struct MyGame {
meshes: Vec<Mesh3D>,
}
impl MyGame {
fn new() -> Self {
let mut meshes = Vec::new();
// Cria várias primitivas
let mut cube = Mesh3D::cube(2.0);
cube.position = Vec3::new(-5.0, 0.0, 0.0);
cube.set_color([255, 0, 0, 255]);
meshes.push(cube);
let mut sphere = Mesh3D::sphere(1.0, 16);
sphere.position = Vec3::new(0.0, 0.0, 0.0);
sphere.set_color([0, 255, 0, 255]);
meshes.push(sphere);
let mut torus = Mesh3D::torus(1.0, 0.3, 16, 12);
torus.position = Vec3::new(5.0, 0.0, 0.0);
torus.set_color([0, 0, 255, 255]);
meshes.push(torus);
// Chão
let mut ground = Mesh3D::grid(20.0, 20.0, 20, 20);
ground.position = Vec3::new(0.0, -2.0, 0.0);
ground.set_color([100, 100, 100, 255]);
meshes.push(ground);
Self { meshes }
}
}
impl Game for MyGame {
fn update(&mut self, engine: &mut Engine) {
// Rotaciona objetos
for mesh in &mut self.meshes[..3] {
mesh.rotation.y += 1.0;
}
// Configura câmera
engine.renderer3d.set_camera(
Vec3::new(10.0, 5.0, 10.0),
Vec3::new(0.0, 0.0, 0.0),
Vec3::new(0.0, 1.0, 0.0),
);
}
fn render(&mut self, engine: &mut Engine) {
engine.renderer.clear([20, 20, 30, 255]);
for mesh in &self.meshes {
engine.renderer3d.draw_mesh(mesh);
}
}
}
fn main() {
let mut engine = Engine::new("3D Primitives", 1280, 720);
let game = MyGame::new();
engine.run(game);
}
```
## 📝 Exemplo de Uso - 2D
```rust
use sevenx_engine::*;
struct MyGame {
time: f32,
}
impl Game for MyGame {
fn update(&mut self, engine: &mut Engine) {
self.time += engine.time.delta_secs();
}
fn render(&mut self, engine: &mut Engine) {
// Limpa a tela
for pixel in engine.pixels.chunks_exact_mut(4) {
pixel.copy_from_slice(&[30, 30, 40, 255]);
}
// Cria o sistema de primitivas
let mut prims = Primitives2D::new(
engine.pixels,
engine.window.width(),
engine.window.height()
);
// Desenha formas
prims.draw_circle_filled(200, 200, 50, [255, 0, 0, 255]);
prims.draw_rect_filled(300, 150, 100, 100, [0, 255, 0, 255]);
prims.draw_triangle_filled(500, 150, 450, 250, 550, 250, [0, 0, 255, 255]);
// Gradiente animado
let radius = 50 + (self.time * 2.0).sin() * 20.0;
prims.draw_gradient_radial(400, 400, radius as i32,
[255, 255, 0, 255], [255, 0, 255, 255]);
// Grade de fundo
prims.draw_grid(50, [50, 50, 50, 100]);
}
}
fn main() {
let mut engine = Engine::new("2D Primitives", 800, 600);
let game = MyGame { time: 0.0 };
engine.run(game);
}
```
## 🎯 Casos de Uso
### Jogos 3D
- **FPS**: Use `capsule` para personagens, `cube` para paredes, `plane` para chão
- **Puzzle**: Use `cube`, `sphere`, `pyramid` para peças
- **Corrida**: Use `cylinder` para rodas, `prism` para pistas
- **Aventura**: Use `torus` para anéis mágicos, `cone` para árvores
### Jogos 2D
- **Platformer**: Use `draw_rect_filled` para plataformas, `draw_circle` para moedas
- **Puzzle**: Use `draw_polygon` para peças, `draw_gradient` para fundos
- **Shooter**: Use `draw_line` para lasers, `draw_circle_filled` para balas
- **UI**: Use `draw_rect`, `draw_gradient_h` para barras de vida/mana
### Visualização
- **Debug**: Use `grid` para referência, `draw_line` para vetores
- **Editor**: Use `draw_grid` para grade, `draw_rect` para seleção
- **Gráficos**: Use `draw_arc` para gráficos de pizza, `draw_gradient` para mapas de calor
## 🚀 Performance
### 3D
- Use `icosphere` em vez de `sphere` para objetos que precisam de geometria uniforme
- Use LOD (Level of Detail) para objetos distantes
- Combine meshes com `merge()` para reduzir draw calls
- Use `grid` com menos subdivisões para terrenos simples
### 2D
- `draw_pixel` é a operação mais rápida
- `draw_line` usa algoritmo de Bresenham (otimizado)
- `draw_circle_filled` é mais lento que `draw_circle`
- `flood_fill` pode ser lento em áreas grandes
- Use `draw_rect_filled` em vez de múltiplos pixels
## 📚 Exemplos Incluídos
Execute os exemplos para ver todas as primitivas em ação:
```bash
# Showcase 3D
cargo run --example primitives_3d_showcase
# Showcase 2D
cargo run --example primitives_2d_showcase
```
## 🎨 Dicas de Design
### Cores
- Use alpha < 255 para transparência
- Combine cores complementares para contraste
- Use gradientes para profundidade
### Composição 3D
- Combine primitivas simples para criar objetos complexos
- Use `merge()` para otimizar objetos compostos
- Varie escalas para criar interesse visual
### Composição 2D
- Use `draw_thick_line` para bordas destacadas
- Combine formas para criar ícones
- Use gradientes para dar profundidade
## 🔧 Customização
### Criar Primitiva 3D Customizada
```rust
let mut custom = Mesh3D::new();
custom.vertices = vec![
Vertex { position: Vec3::new(0.0, 1.0, 0.0), normal: Vec3::new(0.0, 1.0, 0.0), uv: (0.5, 0.0), color: [255, 255, 255, 255] },
// ... mais vértices
];
custom.indices = vec![0, 1, 2, ...];
custom.calculate_normals(); // Calcula normais automaticamente
```
### Criar Padrão 2D Customizado
```rust
fn draw_star(prims: &mut Primitives2D, cx: i32, cy: i32, size: i32, color: [u8; 4]) {
let points = 5;
let mut vertices = Vec::new();
for i in 0..points * 2 {
let angle = i as f32 * std::f32::consts::PI / points as f32;
let radius = if i % 2 == 0 { size } else { size / 2 };
let x = cx + (angle.cos() * radius as f32) as i32;
let y = cy + (angle.sin() * radius as f32) as i32;
vertices.push((x, y));
}
prims.draw_polygon(&vertices, color);
}
```
---
## ⚙️ Sistema de Configurações Gráficas
### Qualidades Disponíveis
O SevenX Engine v0.2.6 inclui 5 níveis de qualidade gráfica:
1. **Muito Baixo** (Padrão) - Para PCs muito fracos
- FPS Alvo: 30
- Partículas: 50
- Resolução: 50%
- Sem pós-processamento
2. **Baixo** - Para PCs fracos
- FPS Alvo: 60
- Partículas: 100
- Resolução: 75%
- Sem pós-processamento
3. **Médio** - Balanceado
- FPS Alvo: 60
- Partículas: 200
- Resolução: 100%
- Pós-processamento básico
4. **Alto** - Para PCs bons
- FPS Alvo: 60
- Partículas: 500
- Resolução: 100%
- Pós-processamento completo
5. **Ultra** - Máxima qualidade
- FPS Alvo: 120
- Partículas: 1000
- Resolução: 100%
- Todos os efeitos
### Uso no Código
```rust
use sevenx_engine::*;
// Carregar configurações
let graphics = GraphicsSettings::load("graphics_settings.json")
.unwrap_or_else(|_| GraphicsSettings::default());
// Aplicar preset
let mut graphics = GraphicsSettings::medium();
// Ajuste dinâmico baseado no FPS
graphics.dynamic_adjust(current_fps);
// Salvar configurações
graphics.save("graphics_settings.json").unwrap();
```
### Exemplo Completo
Execute o demo de configurações gráficas:
```bash
cargo run --example graphics_settings_demo
```
**Controles:**
- TAB/ESC - Menu de configurações
- Setas - Navegar
- Enter - Confirmar
### Arquivo de Configuração
O arquivo `graphics_settings.json` é criado automaticamente com as configurações padrão (Muito Baixo) para garantir que o jogo rode em qualquer PC.
---
**SevenX Engine v0.2.6** - Sistema completo de primitivas 2D e 3D com otimizações! 🎮✨