# Geometry sources: procedural generators and file import

The `wsg::mesh` module is the single entry point for **where the geometry comes from**:
procedural generators or file import.

## Procedural primitives

Each primitive family is behind a **feature** — you only compile what you need.

| Feature | Function | Description |
|---------|----------|-------------|
| `prim-cube` | `cube(size)` | Centered cube, 24 vertices, per-face normals |
| `prim-plane` | `plane(w, d, seg_x, seg_z)` | Horizontal XZ plane (normal +Y), subdivided |
| `prim-sphere` | `uv_sphere(r, sectors, stacks)` | Lat/long sphere, smooth normals |
| `prim-sphere` | `icosphere(r, subdivisions)` | Icosphere (subdivided icosahedron) |
| `prim-cylinder` | `cylinder(r, h, sectors)` | Cylinder (side + caps), analytic normals |
| `prim-cone` | `cone(r, h, sectors)` | Cone (apex + closed base) |
| `prim-torus` | `torus(major, minor, seg_maj, seg_min)` | Torus, smooth normals |

### Default features

```toml
# Your project's Cargo.toml
[dependencies]
wsg-lib = { path = "../lib" }
# Default: all primitives enabled (all-prims)
```

```toml
# Only compile the cube and the sphere:
wsg-lib = { path = "../lib", default-features = false, features = ["prim-cube", "prim-sphere"] }
```

### Usage

```rust
use wsg_lib::prelude::*;

let cube = cube(2.0);
let sphere = uv_sphere(1.0, 32, 16);
let ico = icosphere(1.0, 2);

// All return a Geometry (positions + normals + UVs + indices)
assert_eq!(cube.positions.len(), 24);
```

## File import

| Feature | Function | Format |
|---------|----------|--------|
| `import-obj` | `load_obj(path)` / `parse_obj(str)` | Wavefront OBJ |
| `import-gltf` | `load_gltf(path)` | glTF 2.0 / GLB (stub) |

### OBJ parser

Supports: `v`, `vn`, `vt`, `f` (3–4 vertices, fan triangulation).
If the file has no normals, they are **computed** (area-weighted).

```rust
use wsg_lib::mesh::{load_obj, parse_obj};

// From a file
let geom = load_obj("model.obj")?;

// From a string
let geom = parse_obj("v 0 0 0\nv 1 0 0\nv 0 1 0\nf 1 2 3\n")?;
```

### Errors

```rust
use wsg_lib::mesh::import::MeshImportError;

match load_obj("missing.obj") {
    Ok(geom) => { /* … */ }
    Err(MeshImportError::Io(e)) => eprintln!("file not accessible: {e}"),
    Err(MeshImportError::Parse(e)) => eprintln!("invalid syntax: {e}"),
    Err(MeshImportError::Unsupported(e)) => eprintln!("unsupported feature: {e}"),
}
```

## From `Geometry` to the scene

The `mesh` module produces `Geometry` (CPU data). To render it, go through
`Scene::create_mesh`, which uploads it to the GPU:

```rust
use wsg_lib::prelude::*;
use wsg_lib::mesh::cube;

// In AppHandler::setup:
let geom = cube(1.0);
app.scene.create_mesh("my_mesh", geom, Some("my_mat"))?;
app.scene.add_entity("my_entity", "my_mesh")?;
```

## Example

```sh
cargo run -p wsg-lib --example import --features import-obj -- model.obj
```

## Conventions

- **Y-up**, centered on the origin (except `plane`: XZ plane at y=0)
- **Outward** normals
- UVs in [0,1]²
- **CCW** winding (front face)

## Links

- [User README](../README.md) · [Meshes](meshes.md) · [Materials & textures](materials.md) · [Examples](../examples.md)
- [Root README](../../../README.md)