kiss3d 0.42.0

Keep it simple, stupid, 2D and 3D graphics engine for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

use super::{IndexBuffer, RenderMesh};
use glamx::{Vec2, Vec3};

/// Generates a double-sided subdivided quad mesh.
///
/// Creates a rectangular quad lying on the XY plane, centered at the origin, with its
/// normal pointing along the Z axis. The quad is subdivided into a grid of triangles,
/// making it suitable for height maps or terrain.
///
/// # Arguments
/// * `width` - The quad width (extent along X axis)
/// * `height` - The quad height (extent along Y axis)
/// * `usubdivs` - Number of horizontal subdivisions (squares along width). Must not be 0.
/// * `vsubdivs` - Number of vertical subdivisions (squares along height). Must not be 0.
///
/// # Returns
/// A `RenderMesh` containing the subdivided quad geometry with normals and UVs
///
/// # Example
/// ```no_run
/// # use kiss3d::procedural::quad;
/// // Create a 10x10 quad with 100 subdivisions for a terrain
/// let terrain_mesh = quad(10.0, 10.0, 100, 100);
/// ```
///
/// # Panics
/// Panics if `usubdivs` or `vsubdivs` is 0.
pub fn quad(width: f32, height: f32, usubdivs: usize, vsubdivs: usize) -> RenderMesh {
    let mut quad = unit_quad(usubdivs, vsubdivs);

    let s = Vec3::new(width, height, 1.0);

    quad.scale_by(s);

    quad
}

/// Generates a double-sided quad mesh from a custom grid of vertices.
///
/// Creates a quad with custom vertex positions, useful for creating terrain or
/// deformed surfaces. Normals are automatically computed based on the surface geometry.
///
/// # Arguments
/// * `vertices` - Array of vertex positions defining the surface (must have `nhpoints x nvpoints` elements)
/// * `nhpoints` - Number of points along the horizontal direction (columns)
/// * `nvpoints` - Number of points along the vertical direction (rows)
///
/// # Returns
/// A `RenderMesh` containing the quad geometry with computed normals
///
/// # Example
/// ```no_run
/// # use kiss3d::procedural::quad_with_vertices;
/// # use glamx::Vec3;
/// // Create a 3x3 grid of vertices for a simple heightmap
/// let vertices = vec![
///     Vec3::new(0.0, 0.0, 0.0), Vec3::new(1.0, 0.0, 0.0), Vec3::new(2.0, 0.0, 0.0),
///     Vec3::new(0.0, 0.5, 1.0), Vec3::new(1.0, 0.5, 1.0), Vec3::new(2.0, 0.5, 1.0),
///     Vec3::new(0.0, 0.0, 2.0), Vec3::new(1.0, 0.0, 2.0), Vec3::new(2.0, 0.0, 2.0),
/// ];
/// let quad_mesh = quad_with_vertices(&vertices, 3, 3);
/// ```
///
/// # Panics
/// Panics if `nhpoints` or `nvpoints` is less than 2.
pub fn quad_with_vertices(vertices: &[Vec3], nhpoints: usize, nvpoints: usize) -> RenderMesh {
    assert!(
        nhpoints > 1 && nvpoints > 1,
        "The number of points must be at least 2 in each dimension."
    );

    let mut res = unit_quad(nhpoints - 1, nvpoints - 1);

    for (dest, src) in res.coords.iter_mut().zip(vertices.iter()) {
        *dest = *src;
    }

    res
}

/// Generates a double-sided unit quad mesh.
///
/// Creates a 1x1 quad centered at the origin on the XY plane with its normal pointing
/// along the Z axis. The quad is subdivided into a grid of triangles.
///
/// # Arguments
/// * `usubdivs` - Number of horizontal subdivisions (squares along width). Must not be 0.
/// * `vsubdivs` - Number of vertical subdivisions (squares along height). Must not be 0.
///
/// # Returns
/// A `RenderMesh` containing the unit quad geometry with normals and UVs
///
/// # Example
/// ```no_run
/// # use kiss3d::procedural::unit_quad;
/// // Create a unit quad with 10x10 subdivisions
/// let quad_mesh = unit_quad(10, 10);
/// ```
///
/// # Panics
/// Panics if `usubdivs` or `vsubdivs` is 0.
pub fn unit_quad(usubdivs: usize, vsubdivs: usize) -> RenderMesh {
    assert!(
        usubdivs > 0 && vsubdivs > 0,
        "The number of subdivisions cannot be zero"
    );

    let wstep = 1.0 / (usubdivs as f32);
    let hstep = 1.0 / (vsubdivs as f32);
    let cw = 0.5;
    let ch = 0.5;

    let mut vertices = Vec::new();
    let mut normals = Vec::new();
    let mut triangles = Vec::new();
    let mut tex_coords = Vec::new();

    // create the vertices
    for i in 0usize..vsubdivs + 1 {
        for j in 0usize..usubdivs + 1 {
            let ni: f32 = i as f32;
            let nj: f32 = j as f32;

            let v = Vec3::new(nj * wstep - cw, ni * hstep - ch, 0.0);
            vertices.push(v);
            tex_coords.push(Vec2::new(1.0 - nj * wstep, 1.0 - ni * hstep))
        }
    }

    // create the normals
    for _ in 0..(vsubdivs + 1) * (usubdivs + 1) {
        normals.push(Vec3::new(1.0, 0.0, 0.0))
    }

    // create triangles
    fn dl_triangle(i: u32, j: u32, ws: u32) -> [u32; 3] {
        [(i + 1) * ws + j, i * ws + j, (i + 1) * ws + j + 1]
    }

    fn ur_triangle(i: u32, j: u32, ws: u32) -> [u32; 3] {
        [i * ws + j, i * ws + (j + 1), (i + 1) * ws + j + 1]
    }

    for i in 0usize..vsubdivs {
        for j in 0usize..usubdivs {
            // build two triangles...
            triangles.push(dl_triangle(i as u32, j as u32, (usubdivs + 1) as u32));
            triangles.push(ur_triangle(i as u32, j as u32, (usubdivs + 1) as u32));
        }
    }

    RenderMesh::new(
        vertices,
        Some(normals),
        Some(tex_coords),
        Some(IndexBuffer::Unified(triangles)),
    )
}