MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
PrimitiveMill.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "ComputePress.hpp"
4#include "GraphicsUtils.hpp"
5
7
8namespace MayaFlux::Buffers {
9class VKBuffer;
10}
11
13
14/**
15 * @struct MillSpec
16 * @brief How a PrimitiveMill shapes spans. Stable across dispatches.
17 */
18struct MillSpec {
19 /**
20 * @enum Ribbon
21 * @brief Plane that line ribbons and point quads are built in.
22 *
23 * Neither mode holds a ribbon at a constant pixel width, which requires
24 * expanding after projection. The mill works in world space and does not
25 * do that.
26 */
27 enum class Ribbon : uint8_t {
28 WorldFacing, ///< Turned to face the viewpoint, in world space.
29 WorldPlane ///< Held in the XY plane, viewpoint ignored.
30 };
31
33
34 /**
35 * @brief Take ribbon width and point size from each vertex's own scalar
36 * (LineVertex::thickness, PointVertex::size) instead of
37 * fallback_extent.
38 *
39 * Variation between neighbouring vertices is much more visible in world
40 * space than at a pixel or two of screen width, so a scalar authored as
41 * noise reads as serration along the ribbon.
42 */
43 bool use_vertex_extent { true };
44
45 /**
46 * @brief World units of total ribbon width per unit of a vertex's scalar.
47 *
48 * Line scalars are usually authored as pixel widths, so this maps them into
49 * world space. Set it to 1 when the scalars are already world scale. The
50 * right value depends on the scene, since width does not track screen size.
51 */
52 float width_scale { 0.05F };
53
54 /** @brief World units per unit of a vertex's own size, on point spans. */
55 float point_scale { 0.004F };
56
57 /** @brief Extent used when the layout carries no scalar attribute. */
58 float fallback_extent { 2.0F };
59
60 /**
61 * @brief Write 0..1 UVs across each ribbon and quad instead of copying the
62 * source.
63 *
64 * Lets a fragment shader run a gradient, dash or edge falloff along a
65 * ribbon. Ignored when the layout carries no texture coordinates.
66 *
67 * Point quad corners land in [MILL_POINT_UV_MARKER, +1] instead of [0, 1]
68 * (data/shaders/include/mill_shape.glsl), which is how a shared fragment
69 * shader tells a point quad from a ribbon or a passthrough triangle. Use
70 * mill_is_point() and mill_point_local_uv() rather than testing the
71 * threshold directly.
72 */
73 bool synthesize_uv { true };
74
75 /**
76 * @brief Keep point quads and ribbons unexpanded for an instanced draw.
77 *
78 * The mill places the source position and writes the expansion into the
79 * tangent attribute: a point quad stores its corner offset in xy, a ribbon
80 * stores its unit direction in xyz and its signed half width in w. The
81 * instance vertex shader then faces each instance toward the viewpoint after
82 * its own transform. Applies only to Ribbon::WorldFacing and needs a tangent
83 * attribute in the vertex layout.
84 */
85 bool billboard_instances { false };
86};
87
88/**
89 * @struct MillView
90 * @brief Per-dispatch viewpoint. Used only by MillSpec::Ribbon::WorldFacing.
91 */
92struct MillView {
93 glm::vec3 eye {};
94};
95
96/**
97 * @class PrimitiveMill
98 * @brief Mills spans of mixed primitive topology into one TRIANGLE_LIST vertex
99 * buffer on the GPU.
100 *
101 * Given a source vertex buffer, its layout and a list of DrawRun spans, produces
102 * one triangle buffer with the same vertex layout, so every span can be drawn by
103 * one non-indexed draw at one topology. Points become quads, line segments
104 * become ribbons and triangle spans reduce to lists. Positions are rewritten and
105 * texture coordinates optionally synthesised; every other attribute is copied
106 * bit-exact from the source vertex its corner belongs to, so a vertex shader
107 * written against the source layout consumes the result unchanged.
108 *
109 * Owns its kernel, pipeline and destination buffers and dispatches through
110 * ComputePress. It is not a BufferProcessor: it has no processing token, attach
111 * or chain position, because milling is demand driven by whoever is about to
112 * draw, normally a render processor.
113 *
114 * The output is a transient draw source, not authored geometry. It is
115 * regenerated whenever the spans or the viewpoint change, its vertices have no
116 * correspondence back to the source, and it is not an export or readback
117 * surface.
118 *
119 * ## Limits
120 *
121 * Ribbon width and point size are fixed in world units, so a ribbon thins on
122 * screen as the camera pulls back. Joins are mitred; there are no round joins
123 * or caps. A polyline emitted as duplicated vertex pairs mills twice the
124 * vertices it needs, since every second segment is a zero-length seam that is
125 * skipped but still counted.
126 */
127class MAYAFLUX_API PrimitiveMill {
128public:
129 /**
130 * @param spec Shaping parameters.
131 * @param output_ring Number of milled buffers rotated between dispatches, at
132 * least one.
133 *
134 * A ring of one makes each dispatch wait behind the previous frame's reads.
135 * Each extra slot costs one full copy of the milled geometry, tens of
136 * megabytes for dense line work.
137 */
138 explicit PrimitiveMill(MillSpec spec = {}, uint32_t output_ring = 2);
140
141 PrimitiveMill(const PrimitiveMill&) = delete;
145
146 /**
147 * @brief Vertices @p runs would mill to. No dispatch, no allocation.
148 *
149 * Computed from the spans alone, so the output size is known without a
150 * readback.
151 */
152 [[nodiscard]] static uint32_t milled_vertex_count(std::span<const DrawRun> runs);
153
154 /**
155 * @brief Mill @p runs out of @p source into the owned buffer.
156 * @param source Vertex buffer the spans index into. Must carry a vertex
157 * layout unless @p layout is supplied. The stride must be a multiple
158 * of four bytes and the position attribute word aligned. With an
159 * index buffer, triangle spans count and offset indices; point and
160 * line spans stay vertex addressed.
161 * @param runs Spans to mill, in output order.
162 * @param view Viewpoint, used only by Ribbon::WorldFacing.
163 * @param layout Optional layout describing the source data. Read from
164 * @p source when omitted.
165 * @return Vertices written, or 0 when there was nothing to mill or the
166 * source could not be used.
167 *
168 * Does not wait on its own dispatch. It resolves the previous call's
169 * submission, submits this one and returns. output() can be recorded
170 * against immediately, but it is not valid to read from the host until a
171 * later mill() or release() has resolved the fence.
172 *
173 * Runs on the graphics queue, so a draw submitted afterwards is ordered
174 * after the write. The destination grows to fit and never shrinks.
175 */
176 uint32_t mill(
177 const std::shared_ptr<Buffers::VKBuffer>& source,
178 std::span<const DrawRun> runs,
179 const MillView& view,
180 std::optional<Kakshya::VertexLayout> layout = std::nullopt);
181
182 /**
183 * @brief The milled triangles: the ring slot the last mill() wrote.
184 * @return Null before the first successful mill().
185 *
186 * Fetch again after every mill() rather than caching it; the ring hands back
187 * a different buffer each dispatch.
188 */
189 [[nodiscard]] std::shared_ptr<Buffers::VKBuffer> output() const;
190
191 /** @brief Vertices written by the last mill(). */
192 [[nodiscard]] uint32_t milled_count() const { return m_milled_count; }
193
194 /** @brief The current shaping parameters. */
195 [[nodiscard]] const MillSpec& spec() const { return m_spec; }
196
197 /** @brief Replace the spec. Takes effect on the next mill(). */
198 void set_spec(const MillSpec& spec) { m_spec = spec; }
199
200 /** @brief Destroy the kernel, pipeline and buffers. */
201 void release();
202
203private:
204 /** @brief Compiles the kernel and creates its pipeline with a push descriptor set, once. */
205 bool ensure_kernel();
206
207 /**
208 * @brief Grows the destination ring, run and prefix arenas to fit.
209 *
210 * Every slot is replaced at once and the outgoing buffers are released once
211 * the work submitted so far completes. The 1.5x headroom keeps geometry that
212 * is being added to from re-growing on nearly every cycle.
213 */
214 bool ensure_buffers(
215 const std::shared_ptr<Buffers::VKBuffer>& source,
216 const Kakshya::VertexLayout& layout,
217 uint32_t total,
218 size_t run_count);
219
220 /**
221 * @brief Reclaim every dispatch that has finished, without waiting.
222 *
223 * Releases each finished fence and its command buffer. The run and prefix
224 * slots a dispatch read are freed when its command buffer completes.
225 */
226 void collect_completed();
227
228 /**
229 * @brief Wait on and reclaim every outstanding dispatch.
230 *
231 * For teardown, where the pipeline and shader are about to be destroyed.
232 */
233 void resolve_pending();
234
236
240
241 /// Milled buffers rotated between dispatches, all at m_output_capacity.
242 std::vector<std::shared_ptr<Buffers::VKBuffer>> m_outputs;
243 std::unique_ptr<SlotArena> m_run_arena;
244 std::unique_ptr<SlotArena> m_prefix_arena;
245 size_t m_run_slot { 0 };
246 size_t m_prefix_slot { 0 };
247
248 std::vector<uint32_t> m_prefix;
249 std::vector<uint32_t> m_run_words;
250
251 uint32_t m_output_ring { 2 };
252 size_t m_output_slot { 0 };
253
254 uint32_t m_milled_count { 0 };
255 uint32_t m_output_capacity { 0 };
256
257 /// Dispatches submitted and not yet observed complete, oldest first.
258 std::vector<FenceID> m_in_flight;
259};
260
261/**
262 * @brief Host equivalent of PrimitiveMill::mill, over raw bytes.
263 * @param src Source vertex bytes. Must be four byte aligned.
264 * @param layout Describes @p src. The result carries the same attributes.
265 * @param runs Spans to mill, in output order.
266 * @param spec Shaping parameters, as for the device path.
267 * @param view Viewpoint, as for the device path.
268 * @param dst Resized to hold the result.
269 * @param indices When non-empty, triangle spans address these indices instead of vertices.
270 * @return Layout describing @p dst, which is @p layout with a new vertex_count.
271 *
272 * Gives the kernel a reference to be tested against, and a route for a caller
273 * with no compute queue available. It builds the unjoined ribbon form only (no
274 * miter, no width averaging across shared positions), so use it to check span
275 * indexing and vertex counts rather than ribbon geometry. Not a general geometry
276 * utility, and not intended for per-frame use at scale.
277 */
279 std::span<const uint8_t> src,
280 const Kakshya::VertexLayout& layout,
281 std::span<const DrawRun> runs,
282 const MillSpec& spec,
283 const MillView& view,
284 std::vector<uint8_t>& dst,
285 std::span<const uint32_t> indices = {});
286
287} // namespace MayaFlux::Portal::Graphics
Vulkan-backed buffer wrapper used in processing chains.
Definition VKBuffer.hpp:76
PrimitiveMill(MillSpec spec={}, uint32_t output_ring=2)
std::shared_ptr< Buffers::VKBuffer > output() const
The milled triangles: the ring slot the last mill() wrote.
std::unique_ptr< SlotArena > m_prefix_arena
PrimitiveMill(PrimitiveMill &&)=delete
PrimitiveMill & operator=(PrimitiveMill &&)=delete
uint32_t mill(const std::shared_ptr< Buffers::VKBuffer > &source, std::span< const DrawRun > runs, const MillView &view, std::optional< Kakshya::VertexLayout > layout=std::nullopt)
Mill runs out of source into the owned buffer.
uint32_t milled_count() const
Vertices written by the last mill().
static uint32_t milled_vertex_count(std::span< const DrawRun > runs)
Vertices runs would mill to.
PrimitiveMill(const PrimitiveMill &)=delete
void set_spec(const MillSpec &spec)
Replace the spec.
const MillSpec & spec() const
The current shaping parameters.
std::unique_ptr< SlotArena > m_run_arena
std::vector< std::shared_ptr< Buffers::VKBuffer > > m_outputs
Milled buffers rotated between dispatches, all at m_output_capacity.
PrimitiveMill & operator=(const PrimitiveMill &)=delete
std::vector< FenceID > m_in_flight
Dispatches submitted and not yet observed complete, oldest first.
Kakshya::VertexLayout mill_on_host(std::span< const uint8_t > src, const Kakshya::VertexLayout &layout, std::span< const DrawRun > runs, const MillSpec &spec, const MillView &view, std::vector< uint8_t > &dst, std::span< const uint32_t > indices)
Host equivalent of PrimitiveMill::mill, over raw bytes.
constexpr ShaderID INVALID_SHADER
constexpr ComputePipelineID INVALID_COMPUTE_PIPELINE
Complete description of vertex data layout in a buffer.
Ribbon
Plane that line ribbons and point quads are built in.
@ WorldFacing
Turned to face the viewpoint, in world space.
@ WorldPlane
Held in the XY plane, viewpoint ignored.
bool synthesize_uv
Write 0..1 UVs across each ribbon and quad instead of copying the source.
float fallback_extent
Extent used when the layout carries no scalar attribute.
float width_scale
World units of total ribbon width per unit of a vertex's scalar.
bool billboard_instances
Keep point quads and ribbons unexpanded for an instanced draw.
bool use_vertex_extent
Take ribbon width and point size from each vertex's own scalar (LineVertex::thickness,...
float point_scale
World units per unit of a vertex's own size, on point spans.
How a PrimitiveMill shapes spans.