MayaFlux 0.4.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
SpatialRegionProcessor.hpp
Go to the documentation of this file.
1#pragma once
2
4
5namespace MayaFlux::Kakshya {
6
7/**
8 * @class SpatialRegionProcessor
9 * @brief Parallel spatial extraction processor for image-modality containers.
10 *
11 * Operates on any SignalSourceContainer whose structure carries at least one
12 * spatial dimension (SPATIAL_Y, SPATIAL_X, or SPATIAL_Z). Unlike
13 * RegionOrganizationProcessor — which advances a sequential temporal cursor
14 * through audio regions — this processor extracts *all* active regions on
15 * every process() call, reflecting the parallel readback semantics of spatial
16 * data.
17 *
18 * Region source:
19 * Regions are read from the container's RegionGroup map
20 * (get_all_region_groups()). Each Region inside each group becomes one
21 * OrganizedRegion in m_organized_regions, inheriting both group-level and
22 * region-level attributes. organize_container_data() re-syncs this list
23 * from the live group map, so callers can mutate groups between frames by
24 * calling refresh().
25 *
26 * Processing contract (process()):
27 * - Expects processed_data[0] to hold the full-surface readback as a
28 * std::vector<uint8_t|uint16_t|uint32_t|float> placed there by the
29 * default processor (e.g. WindowAccessProcessor) before the chain runs.
30 * The element type is determined by the live swapchain format; all four
31 * pixel-bearing types are handled natively without conversion.
32 * - Replaces processed_data with one DataVariant per active region,
33 * in group-iteration order, then region-insertion order within each group.
34 * - Each DataVariant carries the attributes from its OrganizedRegion so
35 * downstream consumers can identify the source ("group_name", "region_index").
36 * - If processed_data[0] is absent or empty, state is set to IDLE and the
37 * method returns without modifying processed_data.
38 *
39 * Caching:
40 * Auto-caching is disabled by default. Spatial data from a live surface
41 * changes every frame, so caching individual regions yields no benefit
42 * under normal operation. It can be re-enabled via set_auto_caching(true)
43 * for static or infrequently-updated surfaces (e.g. a paused framebuffer).
44 *
45 * Container neutrality:
46 * No WindowContainer-specific code. Any container that satisfies the
47 * NDDimensionalContainer interface and populates processed_data[0] with a
48 * flat spatial buffer is compatible.
49 */
50class MAYAFLUX_API SpatialRegionProcessor : public RegionProcessorBase {
51public:
53 ~SpatialRegionProcessor() override = default;
54
55 /**
56 * @brief Attach to a spatial container.
57 * Validates that the container has at least one spatial dimension.
58 * Disables auto-caching (appropriate for live surfaces).
59 * Delegates to RegionProcessorBase::on_attach which calls
60 * organize_container_data().
61 * @throws std::invalid_argument if no spatial dimension is found.
62 */
63 void on_attach(const std::shared_ptr<SignalSourceContainer>& container) override;
64
65 /**
66 * @brief Detach; delegates to RegionProcessorBase::on_detach.
67 */
68 void on_detach(const std::shared_ptr<SignalSourceContainer>& container) override;
69
70 /**
71 * @brief Extract all active regions from processed_data[0] in parallel.
72 *
73 * For each OrganizedRegion in m_organized_regions, extracts pixel
74 * data via extract_nd_region and appends to processed_data.
75 * Sets OrganizedRegion::state to ACTIVE during extraction and
76 * PROCESSED on completion. Failed extractions are logged and
77 * skipped without aborting the frame.
78 *
79 * @param container Source container; processed_data[0] must hold the
80 * full-surface buffer.
81 */
82 void process(const std::shared_ptr<SignalSourceContainer>& container) override;
83
84 /**
85 * @brief Re-sync m_organized_regions from the container's current group map.
86 * Call after mutating region groups between frames.
87 */
88 void refresh();
89
90protected:
91 /**
92 * @brief Build m_organized_regions from get_all_region_groups().
93 * Each Region in each RegionGroup becomes one OrganizedRegion whose
94 * attributes include "group_name" (std::string) and "region_index"
95 * (size_t) for downstream identification.
96 */
97 void organize_container_data(
98 const std::shared_ptr<SignalSourceContainer>& container) override;
99};
100
101} // namespace MayaFlux::Kakshya
Base class for N-dimensional region processors.
Parallel spatial extraction processor for image-modality containers.