capture_spatial()

uint32_t MayaFlux::IO::IOManager::capture_spatial	(	const std::string &	filepath,
		std::vector< IO::SpatialCaptureSource >	sources,
		uint32_t	max_frames = 0,
		uint64_t	frame_interval = 1
	)

Begin (or join) recording time-sampled streams into an Alembic archive.

Resolves filepath to a shared SpatialCache: the first call for a given path opens it, and a later call passing the same path reuses the cache already open, so several independent captures can each record their own streams into one archive. Unlike capture_volume, nothing is numbered per frame: Alembic carries time natively, so every sample of every stream lands in the one file across the whole recording.

Spawns a SpatialCapture on the engine scheduler and retains it, the same GraphicsRoutine/FrameDelay shape capture_volume uses. For a capture the caller owns and drives itself, construct IO::SpatialCapture directly against a SpatialCache of its own.

Parameters

filepath	Destination .abc path.
sources	Streams to tick together every frame. Build one with IO::make_network_geometry_source() or a hand-written IO::SpatialCaptureSource.
max_frames	Stop after this many frames. Zero is unbounded.
frame_interval	Frames between captures.

Returns

Capture handle for stop_spatial_capture, or 0 on failure (no sources, no scheduler, or the archive failed to open).

Definition at line 1345 of file IOManager.cpp.

{
    if (sources.empty()) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "capture_spatial: no sources");
        return 0;
    }
 
    if (!m_scheduler) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "capture_spatial: TaskScheduler unavailable");
        return 0;
    }
 
    std::shared_ptr<IO::SpatialCache> cache;
    {
        std::lock_guard lock(m_spatial_captures_mutex);
        auto it = m_spatial_caches.find(filepath);
        if (it != m_spatial_caches.end()) {
            cache = it->second;
        } else {
            auto new_cache = std::make_shared<IO::SpatialCache>();
            if (!new_cache->open(filepath)) {
                MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
                    "capture_spatial: failed to open '{}': {}", filepath, new_cache->get_last_error());
                return 0;
            }
            cache = new_cache;
            m_spatial_caches.emplace(filepath, cache);
        }
        ++m_spatial_cache_refcounts[filepath];
    }
 
    auto capture = std::make_unique<IO::SpatialCapture>(*m_scheduler, cache, std::move(sources));
    capture->start(max_frames, frame_interval);
 
    const uint32_t id = m_next_spatial_capture_id.fetch_add(1, std::memory_order_relaxed);
 
    std::lock_guard lock(m_spatial_captures_mutex);
    m_spatial_captures.emplace(id, SpatialCaptureEntry { .capture = std::move(capture), .filepath = filepath });
    return id;
}

References MayaFlux::IO::IOManager::SpatialCaptureEntry::capture, MayaFlux::Journal::FileIO, MayaFlux::Journal::IO, m_next_spatial_capture_id, m_scheduler, m_spatial_cache_refcounts, m_spatial_caches, m_spatial_captures, m_spatial_captures_mutex, and MF_ERROR.