MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Containment.hpp
Go to the documentation of this file.
1#pragma once
2
10
12
13/**
14 * @brief The spatial fields of an Element as one value: Kinesis::HitRegion2D.
15 *
16 * Any factory may produce one, rectangular or not. bounds must circumscribe
17 * contains, because Layer rejects outside bounds before asking contains.
18 */
20
21/**
22 * @brief Write a hit region onto an element.
23 * @note clip is written only when the region carries one, so a clip set by a
24 * container such as Scrollable survives.
25 */
26inline void apply_containment(Element& element, const Containment& hit)
27{
28 element.with_containment(hit);
29}
30
31/**
32 * @brief A geometry function that draws a value and claims a fixed containment.
33 *
34 * @tparam T State type the draw callable reads.
35 * @param draw Writes the vertex bytes for a value.
36 * @param region Written onto the element on every draw.
37 */
38template <typename T>
40 std::function<void(const T&, std::vector<uint8_t>&)> draw, Containment region)
41{
42 return [draw = std::move(draw), region = std::move(region)](
43 T value, std::vector<uint8_t>& out, Element& element) {
44 draw(value, out);
45 apply_containment(element, region);
46 };
47}
48
49/** @brief The rectangle itself as bounds, with no containment test. */
50[[nodiscard]] inline Containment rect_containment(Kinesis::AABB2D region)
51{
52 return Containment { .bounds = region };
53}
54
55/**
56 * @brief Hit region derived from placed vertex positions.
57 *
58 * Triangle topologies hit inside any non-degenerate triangle. Other
59 * topologies get the circumscribing box as bounds only. In both cases the box
60 * of all positions is the bounds.
61 *
62 * @param positions Placed positions in NDC.
63 * @param topology Primitive topology the positions are drawn with.
64 */
65[[nodiscard]] inline Containment containment_of(
66 std::span<const glm::vec2> positions, Graphics::PrimitiveTopology topology)
67{
68 Containment hit;
69 if (positions.empty())
70 return hit;
71 hit.bounds = Kinesis::aabb(positions);
72
73 using Topology = Graphics::PrimitiveTopology;
74 std::vector<glm::vec2> triangles;
75 if (topology == Topology::TRIANGLE_LIST) {
76 triangles.assign(positions.begin(), positions.end());
77 } else if (topology == Topology::TRIANGLE_STRIP) {
78 for (size_t i = 0; i + 2 < positions.size(); ++i)
79 triangles.insert(triangles.end(), { positions[i], positions[i + 1], positions[i + 2] });
80 } else if (topology == Topology::TRIANGLE_FAN) {
81 for (size_t i = 1; i + 1 < positions.size(); ++i)
82 triangles.insert(triangles.end(), { positions[0], positions[i], positions[i + 1] });
83 }
84 if (!triangles.empty())
86 return hit;
87}
88
89/**
90 * @struct ContainmentSource
91 * @brief What a hit region provider may use: the placed geometry and, when the
92 * placement has one, its bounds.
93 */
95 std::span<const glm::vec2> positions;
97 std::optional<Kinesis::AABB2D> placement;
98};
99
100/**
101 * @brief Produces a hit region from placed geometry, or nullopt with an error.
102 *
103 * Any callable qualifies: a circle, a polygon, a union, a host function. The
104 * provider must return bounds that circumscribe its containment test.
105 */
106using ContainmentProvider = std::function<std::optional<Containment>(const ContainmentSource&, std::string&)>;
107
108/**
109 * @class ContainmentTable
110 * @brief Hit region providers by name.
111 *
112 * A plain value like every table here: nothing is registered until its
113 * builder adds it, and a host, a library or a user each build their own.
114 * A factory that lets a document choose its hit region declares a name
115 * among its described inputs and resolves it here.
116 */
118public:
119 /** @brief Register a provider, replacing any of the same name. */
120 void expose(std::string name, ContainmentProvider provider)
121 {
122 m_providers.insert_or_assign(name, std::move(provider));
123 }
124
125 /** @brief Add another table under a prefix, as FlatMap::merge_prefixed. */
126 bool merge(const ContainmentTable& other, std::string_view prefix,
127 std::string& error, bool replace = false)
128 {
129 return m_providers.merge_prefixed(other.m_providers, prefix, error, replace);
130 }
131
132 [[nodiscard]] bool contains(std::string_view name) const
133 {
134 return m_providers.find(name) != m_providers.end();
135 }
136
137 /** @brief Registered names in sorted order. */
138 [[nodiscard]] std::vector<std::string> names() const
139 {
140 std::vector<std::string> result;
141 for (const auto& entry : m_providers)
142 result.push_back(entry.first);
143 return result;
144 }
145
146 /** @brief Run the provider of this name on a source. */
147 [[nodiscard]] std::optional<Containment> resolve(
148 std::string_view name, const ContainmentSource& source, std::string& error) const
149 {
150 const auto provider = m_providers.find(name);
151 if (provider == m_providers.end()) {
152 error = "no registered hit region " + std::string(name);
153 return std::nullopt;
154 }
155 return std::invoke(provider->second, source, error);
156 }
157
158 /**
159 * @brief The named containment, or the fallback when the name is empty.
160 *
161 * A factory derives its own containment from its geometry and lets an
162 * input name replace it, so the fallback is that derived value.
163 *
164 * @param error Receives the reason when nullopt is returned.
165 */
166 [[nodiscard]] std::optional<Containment> resolve_or(std::string_view name,
167 const ContainmentSource& source, Containment fallback, std::string& error) const
168 {
169 if (name.empty())
170 return fallback;
171 return resolve(name, source, error);
172 }
173
174private:
176};
177
178}
Map kept as one sorted vector, cheap to copy.
Definition FlatMap.hpp:21
std::optional< Containment > resolve_or(std::string_view name, const ContainmentSource &source, Containment fallback, std::string &error) const
The named containment, or the fallback when the name is empty.
bool merge(const ContainmentTable &other, std::string_view prefix, std::string &error, bool replace=false)
Add another table under a prefix, as FlatMap::merge_prefixed.
bool contains(std::string_view name) const
void expose(std::string name, ContainmentProvider provider)
Register a provider, replacing any of the same name.
std::vector< std::string > names() const
Registered names in sorted order.
Memory::FlatMap< std::string, ContainmentProvider, std::less<> > m_providers
std::optional< Containment > resolve(std::string_view name, const ContainmentSource &source, std::string &error) const
Run the provider of this name on a source.
Hit region providers by name.
std::function< bool(glm::vec2)> triangle_list_bounds(std::span< const glm::vec2 > positions)
Containment test for a triangle list: inside any triangle.
Definition Bounds.hpp:535
AABB3D aabb(std::span< T > pts) noexcept
Axis-aligned bounding box of a PositionCarrying span.
HitRegion< glm::vec2, AABB2D > HitRegion2D
Definition HitRegion.hpp:71
std::function< void(T value, std::vector< uint8_t > &out_bytes, Element &element)> GeometryFn
Geometry function signature.
Definition Mapped.hpp:71
GeometryFn< T > geometry_with_containment(std::function< void(const T &, std::vector< uint8_t > &)> draw, Containment region)
A geometry function that draws a value and claims a fixed containment.
std::function< std::optional< Containment >(const ContainmentSource &, std::string &)> ContainmentProvider
Produces a hit region from placed geometry, or nullopt with an error.
Containment rect_containment(Kinesis::AABB2D region)
The rectangle itself as bounds, with no containment test.
Kinesis::HitRegion2D Containment
The spatial fields of an Element as one value: Kinesis::HitRegion2D.
void apply_containment(Element &element, const Containment &hit)
Write a hit region onto an element.
Containment containment_of(std::span< const glm::vec2 > positions, Graphics::PrimitiveTopology topology)
Hit region derived from placed vertex positions.
PrimitiveTopology
Vertex assembly primitive topology.
Axis-aligned bounding rectangle in a 2D coordinate space.
Definition Bounds.hpp:63
std::function< bool(Point)> contains
Authoritative containment test.
Definition HitRegion.hpp:40
std::optional< Box > bounds
Fast reject box; must circumscribe contains when both are set.
Definition HitRegion.hpp:37
std::optional< Kinesis::AABB2D > placement
std::span< const glm::vec2 > positions
Graphics::PrimitiveTopology topology
What a hit region provider may use: the placed geometry and, when the placement has one,...
Element & with_containment(const Kinesis::HitRegion2D &region)
Set bounds_hint and contains from one hit region.
Definition Element.hpp:139
A bounded, renderable region on a window surface.
Definition Element.hpp:62