MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
SpatialCache.hpp
Go to the documentation of this file.
1#pragma once
2
4
6enum class PrimitiveTopology : uint8_t;
7}
8
9namespace MayaFlux::IO {
10
11/**
12 * @enum SpatialScope
13 * @brief How many elements one attribute contributes per sample.
14 *
15 * Mirrors Alembic's own GeometryScope, narrowed to the three values that
16 * apply to points and curves (kVertexScope/kFacevaryingScope are mesh-only
17 * concepts with no equivalent here):
18 * Constant: one value for the whole stream.
19 * Uniform: one value per curve. Meaningless for PrimitiveTopology::POINT_LIST
20 * (a point cloud has no sub-grouping smaller than the stream
21 * itself, so it is treated as Constant there).
22 * Varying: one value per point, or per curve vertex for curve topologies.
23 */
24enum class SpatialScope : uint8_t {
28};
29
30/**
31 * @struct SpatialAttribute
32 * @brief One named, scoped channel of already-typed values.
33 *
34 * values holds one of Kakshya::DataVariant's float/glm::vec2/glm::vec3/
35 * glm::vec4/uint32_t vectors, sized per SpatialScope against the sample it
36 * is attached to (1 for Constant, curve count for Uniform, point/vertex
37 * count for Varying). Any other DataVariant alternative is rejected.
38 *
39 * A vec3 named exactly "color" or "normal" is declared through Alembic's
40 * dedicated color/normal GeomParam types instead of a plain vector one, so
41 * an importer recognizes it as such rather than an arbitrary direction. A
42 * vec4 "color" is written as an RGBA color. Every other vec4 is a float
43 * GeomParam with array extent 4, and every other name stays generic.
44 * MayaFlux's own vertex fields already use these names for these roles.
45 */
51
52/**
53 * @struct SpatialSample
54 * @brief One sample's worth of data for one named stream.
55 *
56 * topology decides which of the remaining fields apply:
57 * POINT_LIST: ids/velocities meaningful, vertex_counts_per_curve must be
58 * empty (every position is its own point).
59 * LINE_LIST / LINE_STRIP: vertex_counts_per_curve required (its sum must
60 * equal positions.size()), ids/velocities must be empty
61 * (Alembic's Curves schema has neither).
62 * Any other topology is rejected: triangle data belongs to ModelWriter, not
63 * this class.
64 */
67 std::span<const glm::vec3> positions;
68 std::span<const int32_t> vertex_counts_per_curve;
69 std::span<const uint64_t> ids;
70 std::span<const glm::vec3> velocities;
71 std::span<const SpatialAttribute> attributes;
72};
73
74/**
75 * @class SpatialCache
76 * @brief Alembic-backed writer for time-sampled spatial entity state:
77 * particle systems, point clouds, inferred topology, and any other
78 * positions-plus-named-attributes-over-time source.
79 *
80 * Named after what it does, not the backend library or one data shape:
81 * this is a cache of spatial state over time, not "the Alembic class."
82 * Alembic is an implementation detail hidden behind Impl, the same
83 * convention ModelReader uses to keep Assimp headers out of its own
84 * public interface.
85 *
86 * Deliberately not registry-dispatched like ModelWriter/VolumeWriter: those
87 * registries exist because several backend libraries could plausibly
88 * implement the same format-agnostic contract. No second library writes
89 * .abc files, so a registry here would be indirection with nothing to
90 * dispatch between.
91 *
92 * Each named stream keeps its own Alembic sample count: calling write()
93 * for a given stream_name appends one sample to that stream's own
94 * timeline. There is no separate "advance time" step; Alembic's own
95 * OTypedSchema::set() is what appends, and calling it once per capture
96 * tick per stream already produces the sequence. Streams written at
97 * different cadences (e.g. particles every frame, bonds only when they
98 * change) simply end up with different sample counts on their own
99 * timelines, which Alembic permits.
100 *
101 * Object-level metadata (write_metadata) is Alembic MetaData, fixed at the
102 * point a stream's underlying object is first created and not
103 * retroactively settable by Alembic's own API. Call write_metadata for a
104 * stream_name before its first write() call for the tags to take effect;
105 * calling it after is logged and ignored.
106 *
107 * Usage:
108 * @code
109 * IO::SpatialCache cache;
110 * cache.open("swarm.abc");
111 *
112 * cache.write_metadata("particles", { { "operator", "PhysicsOperator" } });
113 * cache.write("particles", {
114 * .topology = Portal::Graphics::PrimitiveTopology::POINT_LIST,
115 * .positions = positions,
116 * .ids = ids,
117 * .attributes = attributes,
118 * });
119 * // ... one write() call per capture tick ...
120 *
121 * cache.close();
122 * @endcode
123 */
124class MAYAFLUX_API SpatialCache {
125public:
126 SpatialCache();
128
129 SpatialCache(const SpatialCache&) = delete;
132 SpatialCache& operator=(SpatialCache&&) noexcept;
133
134 /**
135 * @brief Open an Alembic archive for writing, Ogawa backend.
136 * @param filepath Destination path. Anchored via resolve_write_path.
137 * @return True on success. On failure call get_last_error().
138 */
139 bool open(const std::string& filepath);
140
141 /**
142 * @brief Append one sample to a named stream.
143 *
144 * Creates the stream's underlying Alembic object on first call for
145 * this stream_name (applying any tags queued by write_metadata) and
146 * declares each attribute's OGeomParam at that point. Subsequent calls
147 * for the same stream_name must keep passing the same topology and the
148 * same attributes (same names, types, scopes, same order): declaration
149 * is one-time, only values change per sample.
150 *
151 * @param stream_name Name this stream is written under.
152 * @param sample This sample's data. See SpatialSample's own doc
153 * for which fields apply to which topology.
154 * @return True on success. On failure call get_last_error().
155 */
156 bool write(const std::string& stream_name, const SpatialSample& sample);
157
158 /**
159 * @brief Queue object-level metadata tags for a named stream.
160 *
161 * Must be called before that stream_name's first write() call: Alembic
162 * MetaData is fixed at object creation and cannot be changed
163 * afterward. A call arriving after the stream's object already exists
164 * is logged and has no effect.
165 *
166 * @param stream_name Stream these tags apply to.
167 * @param tags Key-value pairs, e.g. run parameters
168 * (gravity, bounds, rule shader name).
169 * @return True if queued. False only if the stream's object was
170 * already created before this call.
171 */
172 bool write_metadata(
173 const std::string& stream_name,
174 const std::unordered_map<std::string, std::string>& tags);
175
176 /**
177 * @brief Finalize and close the archive.
178 *
179 * Safe to call on an unopened or already-closed cache; both are no-ops.
180 */
181 void close();
182
183 [[nodiscard]] std::string get_last_error() const { return m_last_error; }
184
185private:
186 struct Impl;
187 std::unique_ptr<Impl> m_impl;
188
189 mutable std::string m_last_error;
190
191 void set_error(std::string msg) const { m_last_error = std::move(msg); }
192
193 bool write_vertex_sample(const std::string& stream_name, const SpatialSample& sample);
194 bool write_curves_sample(const std::string& stream_name, const SpatialSample& sample);
195};
196
197} // namespace MayaFlux::IO
std::unique_ptr< Impl > m_impl
bool write_metadata(const std::string &stream_name, const std::unordered_map< std::string, std::string > &tags)
Queue object-level metadata tags for a named stream.
SpatialCache(SpatialCache &&) noexcept
std::string get_last_error() const
bool open(const std::string &filepath)
Open an Alembic archive for writing, Ogawa backend.
SpatialCache & operator=(const SpatialCache &)=delete
void set_error(std::string msg) const
SpatialCache(const SpatialCache &)=delete
bool write(const std::string &stream_name, const SpatialSample &sample)
Append one sample to a named stream.
void close()
Finalize and close the archive.
SpatialScope
How many elements one attribute contributes per sample.
std::variant< std::vector< double >, std::vector< float >, std::vector< uint8_t >, std::vector< uint16_t >, std::vector< uint32_t >, std::vector< std::complex< float > >, std::vector< std::complex< double > >, std::vector< glm::vec2 >, std::vector< glm::vec3 >, std::vector< glm::vec4 >, std::vector< glm::mat4 > > DataVariant
Multi-type data storage for different precision needs.
Definition NDData.hpp:58
PrimitiveTopology
Vertex assembly primitive topology.
Kakshya::DataVariant values
One named, scoped channel of already-typed values.
std::span< const glm::vec3 > positions
std::span< const glm::vec3 > velocities
std::span< const SpatialAttribute > attributes
Portal::Graphics::PrimitiveTopology topology
std::span< const int32_t > vertex_counts_per_curve
std::span< const uint64_t > ids
One sample's worth of data for one named stream.