MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
VolumeWriter.hpp
Go to the documentation of this file.
1#pragma once
2
5
6namespace MayaFlux::IO {
7
8/**
9 * @struct VolumeWriteOptions
10 * @brief Configuration for volume writing.
11 *
12 * Format-specific knobs are interpreted by the concrete writer; unsupported
13 * options are silently ignored.
14 */
16 /**
17 * @brief Magnitude below which a cell is written as inactive.
18 *
19 * Compared against the absolute value of a scalar and against the length
20 * of a vector. Cells that fall below take the background value and cost
21 * nothing in a sparse format, so this is the setting that decides file
22 * size for a simulation field that is mostly empty.
23 *
24 * Applies to every field unless overridden in field_thresholds.
25 */
26 float activity_threshold { 1e-6F };
27
28 /**
29 * @brief Per-field overrides of activity_threshold, keyed by field name.
30 *
31 * A volume carrying density in [0, 1] alongside a pressure field spanning
32 * several orders of magnitude has no single correct threshold. Names not
33 * present here fall back to activity_threshold; names present but not
34 * declared in the data are ignored without complaint.
35 */
36 std::unordered_map<std::string, float> field_thresholds;
37
38 /**
39 * @brief Value assumed by every inactive cell.
40 *
41 * Zero suits a density, a temperature, or any quantity whose absence is
42 * an absence. A level set wants the signed narrow-band width instead, so
43 * that space outside the stored band reads as far from the surface rather
44 * than on it.
45 */
46 float background { 0.0F };
47
48 /**
49 * @brief Store values at half precision where the format supports it.
50 *
51 * Halves the payload. Adequate for anything destined for rendering,
52 * inadequate for a field that will be simulated further downstream.
53 */
54 bool half_float { false };
55
56 /**
57 * @brief Format-specific compression code, or -1 for the writer's default.
58 *
59 * Matches the convention in ImageWriteOptions rather than enumerating
60 * codes that differ per format.
61 */
62 int compression { -1 };
63};
64
65/**
66 * @class VolumeWriter
67 * @brief Abstract base for volumetric format writers.
68 *
69 * Parallels ImageWriter. Each concrete writer handles one or more file
70 * extensions and is responsible for validating that the supplied VolumeData
71 * is something its format can express: a format with no vector grid type
72 * rejects a vector field rather than silently dropping a component.
73 *
74 * Writers are single-shot: one call to write() produces one file. A frame
75 * sequence is a sequence of calls with different paths, since no volumetric
76 * format in common use carries time within a single file.
77 *
78 * A writer receives host memory and nothing else. No Vulkan, no buffer, no
79 * knowledge of what produced the values.
80 */
81class MAYAFLUX_API VolumeWriter {
82public:
83 virtual ~VolumeWriter() = default;
84
85 /**
86 * @brief Check whether this writer handles the given filepath.
87 */
88 [[nodiscard]] virtual bool can_write(const std::string& filepath) const = 0;
89
90 /**
91 * @brief Write volume data to disk.
92 * @param filepath Destination path.
93 * @param data Volume data. Must satisfy VolumeData::is_consistent().
94 * @param options Format-specific options.
95 * @return true on success. On failure call get_last_error().
96 */
97 virtual bool write(
98 const std::string& filepath,
99 const Kakshya::VolumeData& data,
100 const VolumeWriteOptions& options = {}) = 0;
101
102 /**
103 * @brief File extensions handled by this writer (without dot).
104 */
105 [[nodiscard]] virtual std::vector<std::string> get_supported_extensions() const = 0;
106
107 /**
108 * @brief Last error message or empty string.
109 */
110 [[nodiscard]] virtual std::string get_last_error() const = 0;
111};
112
114
115/**
116 * @brief Singleton registry dispatching volume writes by file extension.
117 *
118 * See WriterRegistry for behavior. Concrete writers register themselves
119 * during subsystem init.
120 */
122
123} // namespace MayaFlux::IO
virtual bool can_write(const std::string &filepath) const =0
Check whether this writer handles the given filepath.
virtual ~VolumeWriter()=default
virtual std::vector< std::string > get_supported_extensions() const =0
File extensions handled by this writer (without dot).
virtual bool write(const std::string &filepath, const Kakshya::VolumeData &data, const VolumeWriteOptions &options={})=0
Write volume data to disk.
virtual std::string get_last_error() const =0
Last error message or empty string.
Abstract base for volumetric format writers.
Singleton registry dispatching single-shot writes by file extension.
WriterFactory< VolumeWriter > VolumeWriterFactory
WriterRegistry< VolumeWriter > VolumeWriterRegistry
Singleton registry dispatching volume writes by file extension.
std::function< std::unique_ptr< Writer >()> WriterFactory
float activity_threshold
Magnitude below which a cell is written as inactive.
bool half_float
Store values at half precision where the format supports it.
int compression
Format-specific compression code, or -1 for the writer's default.
float background
Value assumed by every inactive cell.
std::unordered_map< std::string, float > field_thresholds
Per-field overrides of activity_threshold, keyed by field name.
Configuration for volume writing.
A lattice and every field sampled over it, held in host memory.