Skip to main content

Grid.ixx File

Basic grid shape for rendering. More...

Included Headers​

#include <stdexcept> #include <vector> #include <helios.rendering.mesh.PrimitiveType> #include <helios.rendering.Vertex> #include <helios.math.types> #include <helios.rendering.asset.shape.Shape>

Namespaces Index​

namespacehelios
namespacerendering

Graphics rendering infrastructure. More...

namespaceasset

Rendering asset management. More...

namespaceshape

Geometric shape definitions. More...

namespacebasic

Basic primitive shapes. More...

Classes Index​

structGrid

A configurable grid shape for rendering reference lines in 3D space. More...

Description​

Basic grid shape for rendering.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file Grid.ixx
3 * @brief Basic grid shape for rendering.
4 */
5module;
6
7
8#include <stdexcept>
9#include <vector>
10
11export module helios.rendering.asset.shape.basic.Grid;
12
13import helios.rendering.asset.shape.Shape;
14import helios.rendering.Vertex;
15import helios.math.types;
16import helios.rendering.mesh.PrimitiveType;
17
18using namespace helios::rendering;
19
20export namespace helios::rendering::asset::shape::basic {
21
22 /**
23 * @brief A configurable grid shape for rendering reference lines in 3D space.
24 *
25 * @details The Grid class generates a planar grid mesh composed of line segments. The grid
26 * is centered at the origin and spans from -1 to 1 on both the X and Y axes. The number
27 * of subdivisions along each axis can be configured via constructor parameters.
28 *
29 * The generated grid lies in the XY-plane with all vertices having a Z-coordinate of 0
30 * All normals point in the positive Z direction (0, 0, 1).
31 *
32 * Typical use cases include:
33 * - Scene orientation and scale reference
34 * - Debug visualization
35 * - Editor overlays
36 *
37 * Example usage:
38 * ```cpp
39 * // Create a 10x10 grid
40 * auto grid = std::make_shared<Grid>(10, 10);
41 * scene->addRenderable(grid);
42 * ```
43 *
44 * @note The grid uses `PrimitiveType::Lines` for rendering, not triangles.
45 *
46 * @see Shape
47 */
48 struct Grid : public Shape {
49
50 private:
51 /**
52 * @brief Generates vertex and index data for the grid geometry.
53 *
54 * @details Creates a grid of vertices in the XY-plane spanning from (-1, -1) to (1, 1).
55 * Vertices are generated row by row, and indices are created to form horizontal and
56 * vertical line segments connecting adjacent vertices.
57 *
58 * @param segmentsX Number of subdivisions along the X-axis.
59 * @param segmentsY Number of subdivisions along the Y-axis.
60 *
61 * @return A pair containing the vertex list and the index list for line rendering.
62 *
63 * @throws std::invalid_argument If either segmentsX or segmentsY is less than 2
64 */
65 static std::pair<
66 std::vector<Vertex>,
67 std::vector<unsigned int>
68 > generate(
69 unsigned int segmentsX, unsigned int segmentsY
70 ) {
71 if (segmentsY < 2 || segmentsX < 2) {
72 throw std::invalid_argument("Segments must at least be 2.");
73 }
74 std::vector<Vertex> vertices;
75 std::vector<unsigned int> indices;
76
77 vertices.reserve((segmentsX + 1) * (segmentsY + 1));
78
79 const float quotX = 2.0f/static_cast<float>(segmentsX);
80 const float quotY = 2.0f/static_cast<float>(segmentsY);
81
82 for (int i = 0; i < segmentsX+1; i++) {
83 float x = -1.0f + i * quotX;
84
85 for (int j = 0; j < segmentsY + 1; j++) {
86 float y = -1.0f + j * quotY;
87
88 vertices.push_back({
89 {x, y, 0.0f},
90 {0.0f, 0.0f, 1.0f},
91 {0.5f, 0.5f}
92 });
93
94 if (i >= segmentsX || j >= segmentsY) {
95 continue;
96 }
97
98 if (i > 0) {
99 unsigned int idx = (i) * (segmentsY + 1) + j;
100 indices.push_back(idx);
101 indices.push_back(idx +1);
102 }
103
104 if (j > 0) {
105 unsigned int idx = i * (segmentsY + 1) + j;
106 indices.push_back(idx);
107 indices.push_back(idx + 1 + segmentsY);
108 }
109 }
110
111 }
112
113 return std::pair(vertices, indices);
114 }
115
116 /**
117 * @brief Private constructor that takes pre-generated geometry data.
118 *
119 * @details Used internally by the public constructors to initialize the base Shape
120 * class with vertex and index data.
121 *
122 * @param data A pair containing vertex data and index data for the grid.
123 */
124 explicit Grid(std::pair<std::vector<Vertex>, std::vector<unsigned int>> data) :
125 Shape(std::move(data.first), std::move(data.second))
126 {
127 }
128
129
130 public:
131 /**
132 * @brief Creates a default grid with 2 segments per coordinate axis.
133 *
134 * @details Constructs a simple 2x2 grid, resulting in a cross-like pattern
135 * with one horizontal and one vertical subdivision.
136 */
137 Grid() : Grid(2, 2) {}
138
139 /**
140 * @brief Creates a grid with a specified number of subdivisions.
141 *
142 * @details Constructs a grid with the given number of segments along each axis.
143 * Higher segment counts produce finer grids with more lines.
144 *
145 * @param segmentsX Number of subdivisions along the X-axis. Must be at least 2
146 * @param segmentsY Number of subdivisions along the Y-axis. Must be at least 2
147 *
148 * @throws std::invalid_argument If either segmentsX or segmentsY is less than 2
149 */
150 explicit Grid(unsigned int segmentsX, unsigned int segmentsY) :
151 Grid(generate(segmentsX, segmentsY))
152 { }
153
154 /**
155 * @brief Returns the primitive type used for rendering this shape.
156 *
157 * @return `PrimitiveType::Lines` since the grid is rendered as line segments.
158 */
159 [[nodiscard]] helios::rendering::mesh::PrimitiveType primitiveType() const noexcept override {
160 return mesh::PrimitiveType::Lines;
161 }
162 };
163
164}

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.