MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
TensorInsertion.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "Tensor.hpp"
4
5namespace MayaFlux::Kakshya {
6
7struct Region;
8
9/**
10 * @class TensorInsertion
11 * @brief Mutable adapter for writing into a TensorData.
12 *
13 * Writes typed values or raw bytes, copies a whole view into the tensor,
14 * reshapes, resizes, and attaches axes or quantization. Every call validates
15 * against the tensor's spec and returns false, leaving the tensor unchanged,
16 * on a mismatch.
17 *
18 * Usage:
19 * @code
20 * TensorInsertion insert(weights);
21 * insert.write<float>(values, 0);
22 * insert.reshape({ 64, 3, 7, 7 });
23 * @endcode
24 *
25 * @note The destination must outlive the adapter.
26 */
27class MAYAFLUX_API TensorInsertion {
28public:
29 /** @brief Borrow the tensor to write into. */
30 explicit TensorInsertion(TensorData& tensor) noexcept
31 : m_tensor(&tensor)
32 {
33 }
34
35 /**
36 * @brief Write typed values into a dense tensor.
37 * @tparam T Element type equal to the tensor dtype.
38 * @param values Elements to write.
39 * @param first_element Index of the first element to overwrite.
40 * @return False for a dtype mismatch, a strided layout or a range past the end.
41 */
42 template <TensorElement T>
43 bool write(std::span<const T> values, uint64_t first_element = 0)
44 {
45 if (!m_tensor->m_spec.dtype.is<T>())
46 return false;
47 return write_bytes(std::as_bytes(values), first_element * sizeof(T));
48 }
49
50 /**
51 * @brief Write raw bytes into the elements of a dense tensor.
52 * @param bytes Bytes to write.
53 * @param byte_offset Offset from element zero.
54 * @return False for a strided layout or a range past the end.
55 */
56 bool write_bytes(std::span<const std::byte> bytes, uint64_t byte_offset = 0);
57
58 /**
59 * @brief Overwrite the tensor with a copy of a view of the same dtype and shape.
60 *
61 * Strided views are gathered into the tensor's own layout.
62 */
63 bool assign(const TensorAccess& view);
64
65 /**
66 * @brief Overwrite the box a Region selects with a view of the box's shape.
67 *
68 * Strided views are gathered first, so the source may alias this tensor.
69 * @return False for a dtype mismatch, a shape that differs from the box,
70 * an invalid region, or a sub-byte type unless the region covers the
71 * whole tensor.
72 */
73 bool assign_window(const Region& region, const TensorAccess& view);
74
75 /**
76 * @brief Change the shape without moving data.
77 * @param shape New shape with the same element count; the tensor becomes dense.
78 * @return False when the count differs or the tensor is strided.
79 */
80 bool reshape(std::vector<uint64_t> shape);
81
82 /**
83 * @brief Replace the shape and reallocate.
84 *
85 * Existing elements are kept where positions overlap in flat order and the
86 * rest are zero. The tensor becomes dense with no byte offset.
87 */
88 bool resize(std::vector<uint64_t> shape);
89
90 /** @brief Attach per-axis roles and names; the count must equal the rank. */
91 bool set_axes(std::vector<DataDimension> axes);
92 /** @brief Attach or clear quantization; it must be consistent with the shape. */
93 bool set_quantization(std::optional<TensorQuantization> quantization);
94 /** @brief Rename the tensor. */
95 void set_name(std::string name) { m_tensor->m_spec.name = std::move(name); }
96
97private:
99};
100
101}
Validated, non-owning view of tensor memory and its layout.
Owning host tensor: a TensorSpec and the bytes it describes.
Definition Tensor.hpp:42
void set_name(std::string name)
Rename the tensor.
bool write(std::span< const T > values, uint64_t first_element=0)
Write typed values into a dense tensor.
TensorInsertion(TensorData &tensor) noexcept
Borrow the tensor to write into.
bool write_bytes(std::span< const std::byte > bytes, uint64_t byte_offset=0)
Write raw bytes into the elements of a dense tensor.
Represents a point or span in N-dimensional space.
Definition Region.hpp:74