Depot.hpp

Go to the documentation of this file.

#pragma once
 
#include "MayaFlux/Kakshya/Region/Region.hpp"
 
/**
 * @file API/Depot.hpp
 * @brief Dialog-backed loading and file-type helpers
 *
 * This header provides the public API for working with IOManager,
 * container creation, and file type checking within the MayaFlux engine.
 * It includes:
 * - `create_container<ContainerType>(args...)`: Template function to create signal source containers.
 * - `is_audio(filepath)`, `is_image(filepath)`, and
 *   `is_composite(filepath)`: Check supported file categories.
 * - `get_io_manager()`: Access the global IOManager instance for file loading and buffer management.
 */
 
namespace MayaFlux {
 
namespace Core {
    class VKImage;
}
 
namespace IO {
    class IOManager;
    struct VideoLoadConfig;
    struct ImageWriteOptions;
    struct VolumeWriteOptions;
    struct ModelWriteOptions;
    struct SpatialCaptureSource;
    using TextureResolver = std::function<std::shared_ptr<Core::VKImage>(const std::string&)>;
}
 
namespace Kakshya {
    class CameraContainer;
    class CompositeContainer;
    class CompositeLayout;
    class SoundStreamContainer;
    class SoundFileContainer;
    class DynamicSoundStream;
    class SignalSourceContainer;
    class VideoFileContainer;
    class VideoStreamContainer;
}
 
namespace Buffers {
    class SoundContainerBuffer;
    class VideoContainerBuffer;
    class TextureBuffer;
    class MeshBuffer;
    class VolumeGridBuffer;
}
 
namespace Nodes::Network {
    class MeshNetwork;
}
 
/**
 * @brief creates a new container of the specified type
 * @tparam ContainerType Type of container to create (must be derived from SignalSourceContainer)
 * @tparam Args Constructor argument types
 * @param args Constructor arguments for the container
 * @return Shared pointer to the created container
 */
template <typename ContainerType, typename... Args>
    requires std::derived_from<ContainerType, Kakshya::SignalSourceContainer>
auto create_container(Args&&... args) -> std::shared_ptr<ContainerType>
{
    return std::make_shared<ContainerType>(std::forward<Args>(args)...);
}
 
/**
 * @brief Constructs and initializes per-channel SoundContainerBuffers without registering them.
 * @param container Source container.
 * @return One buffer per channel, unregistered, ready for manual routing.
 */
MAYAFLUX_API std::vector<std::shared_ptr<Buffers::SoundContainerBuffer>>
prepare_audio_buffers(const std::shared_ptr<Kakshya::SoundFileContainer>& container);
 
/**
 * @brief Checks if the given file is an audio file based on its extension
 * @param filepath Path to the file to check
 * @return true if the file is recognized as an audio file, false otherwise
 */
MAYAFLUX_API bool is_audio(const std::filesystem::path& filepath);
 
/**
 * @brief Checks if the given file is an image file based on its extension
 * @param filepath Path to the file to check
 * @return true if the file is recognized as an image file, false otherwise
 */
MAYAFLUX_API bool is_image(const std::filesystem::path& filepath);
 
/**
 * @brief Check whether an existing file has a supported Composite format.
 * @param filepath Path to a CSV or TSV file.
 * @return True for an existing regular file with a supported extension.
 */
MAYAFLUX_API bool is_composite(const std::filesystem::path& filepath);
 
/**
 * @brief The buffer a video or camera container was hooked to.
 *
 * Hooking happens through `| Graphics` or IOManager::hook_*. Returns nullptr
 * when the container has not been hooked.
 */
MAYAFLUX_API std::shared_ptr<Buffers::VideoContainerBuffer> get_associated_buffer(
    const std::shared_ptr<Kakshya::VideoStreamContainer>& container);
 
/**
 * @brief The per-channel buffers an audio container was hooked to.
 *
 * Empty when the container has not been hooked.
 */
MAYAFLUX_API std::vector<std::shared_ptr<Buffers::SoundContainerBuffer>> get_associated_buffers(
    const std::shared_ptr<Kakshya::SoundFileContainer>& container);
 
/**
 * @brief The audio buffers of a video file's extracted sound track.
 *
 * Empty when the video was loaded without VideoReadOptions::EXTRACT_AUDIO,
 * has no audio track, or has not been hooked.
 */
MAYAFLUX_API std::vector<std::shared_ptr<Buffers::SoundContainerBuffer>> get_associated_buffers(
    const std::shared_ptr<Kakshya::VideoFileContainer>& container);
 
// ─────────────────────────────────────────────────────────────────────────
// Dialog-backed load — open
// ─────────────────────────────────────────────────────────────────────────
 
/**
 * @brief Present a native open-file dialog filtered to audio formats and load
 *        the chosen file via IOManager::load_audio().
 *
 * Blocks until the user confirms or cancels. Returns nullptr on cancellation,
 * backend error, or if Portal::System is not initialized.
 */
MAYAFLUX_API std::shared_ptr<Kakshya::SoundFileContainer> choose_audio();
 
/**
 * @brief Present a native open-file dialog filtered to audio formats and load
 *        the chosen file via IOManager::load_audio_bounded().
 *
 * Blocks until the user confirms or cancels. Returns nullptr on cancellation,
 * backend error, or if Portal::System is not initialized.
 *
 * @param max_frames Upper bound on frame count. 0 loads five seconds.
 * @param truncate   If true, truncate files longer than max_frames.
 */
MAYAFLUX_API std::shared_ptr<Kakshya::DynamicSoundStream> choose_audio_bounded(
    uint64_t max_frames = 0, bool truncate = false);
 
/**
 * @brief Present a native open-file dialog filtered to video formats and load
 *        the chosen file via IOManager::load_video(path, config).
 *
 * Returns IO::VideoLoadResult: the video container, then its audio. With
 * VideoReadOptions::EXTRACT_AUDIO in config.video_options the audio track is
 * decoded and returned; otherwise, or for a file with no audio track, the audio
 * is nullptr.
 *
 * Blocks until the user confirms or cancels. Both are nullptr on cancellation,
 * backend error, or if Portal::System is not initialized.
 *
 * @param config Load options forwarded to IOManager::load_video.
 */
MAYAFLUX_API std::pair<std::shared_ptr<Kakshya::VideoFileContainer>, std::shared_ptr<Kakshya::SoundFileContainer>>
choose_video(const IO::VideoLoadConfig& config);
 
/**
 * @brief Let the user pick a camera, and optionally a capture mode, then open
 *        it via IOManager::open_camera().
 *
 * The pickers are Portal::Forma windows driven by the engine. Blocks until
 * the user chooses or closes a window. Returns the opened container, ready for
 * IOManager::hook_camera_to_buffer(), or nullptr on cancellation, when no
 * camera is found, or if the camera fails to open. Portal::Forma must be
 * initialized and the engine running.
 *
 * Modes come from the camera source's presets. A mode is a request: the
 * source falls back to the nearest mode the device accepts.
 *
 * @param choose_mode If false, skip the mode picker and open with the
 *                    default CameraConfig size and frame rate.
 */
MAYAFLUX_API std::shared_ptr<Kakshya::CameraContainer> choose_camera(
    bool choose_mode = true);
 
/**
 * @brief Present a native open-file dialog filtered to image formats and load
 *        the chosen file via IOManager::load_image().
 *
 * Blocks until the user confirms or cancels. Returns nullptr on cancellation,
 * backend error, or if Portal::System is not initialized.
 * @param desired_channels Channel count passed to ImageReader (0 keeps the source layout).
 * @param region Optional source-pixel rectangle with inclusive end coordinates.
 */
MAYAFLUX_API std::shared_ptr<Buffers::TextureBuffer> choose_image(
    int desired_channels = 4,
    std::optional<Kakshya::Region> region = std::nullopt);
 
/**
 * @brief Choose a CSV or TSV file and load it as a CompositeContainer.
 *
 * Every field is UTF-8 text. For bounded reading of large files, use
 * IOManager directly.
 *
 * @return Loaded container, or nullptr on cancellation or failure.
 */
MAYAFLUX_API std::shared_ptr<Kakshya::CompositeContainer> choose_composite();
 
/**
 * @brief Choose a CSV or TSV file and load it with an exact field layout.
 *
 * Mirrors IOManager::load_composite(path, layout, batch_size).
 *
 * @param layout     Field layout for typed CSV/TSV values.
 * @param batch_size Container materialization batch size.
 * @return Loaded container, or nullptr on cancellation or failure.
 */
MAYAFLUX_API std::shared_ptr<Kakshya::CompositeContainer> choose_composite(
    const Kakshya::CompositeLayout& layout, size_t batch_size = 1);
 
/**
 * @brief Present a native open-file dialog filtered to 3D model formats and load
 *        the chosen file via IOManager::load_mesh().
 *
 * Blocks until the user confirms or cancels. Returns an empty vector on
 * cancellation, backend error, or if Portal::System is not initialized.
 */
MAYAFLUX_API std::vector<std::shared_ptr<Buffers::MeshBuffer>> choose_mesh();
 
/**
 * @brief Present a native open-file dialog filtered to 3D model formats and load
 *        the chosen file as a MeshNetwork via IOManager::load_mesh_network().
 *
 * @param resolver Optional texture resolver; null uses the IOManager default.
 *
 * Blocks until the user confirms or cancels. Returns nullptr on cancellation,
 * backend error, or if Portal::System is not initialized.
 */
MAYAFLUX_API std::shared_ptr<Nodes::Network::MeshNetwork>
choose_mesh_network(IO::TextureResolver resolver = nullptr);
 
/**
 * @brief Present a native open-file dialog filtered to volume formats and
 *        load the chosen file via IOManager::load_volume().
 *
 * Blocks until the user confirms or cancels. Returns nullptr on cancellation,
 * backend error, or if Portal::System is not initialized.
 */
MAYAFLUX_API std::shared_ptr<Buffers::VolumeGridBuffer> choose_volume();
 
// ─────────────────────────────────────────────────────────────────────────
// Dialog-backed save
// ─────────────────────────────────────────────────────────────────────────
 
/**
 * @brief Present a native save-file dialog and write @p container to the
 *        chosen path via IOManager::write().
 *
 * Blocks until the user confirms or cancels. The encode task is queued
 * asynchronously; this function returns once the path is chosen and the
 * task is enqueued. Returns false on cancellation, backend error, or if
 * Portal::System is not initialized.
 *
 * @param container      Source container to encode.
 * @param suggested_name Filename pre-filled in the dialog name field.
 */
MAYAFLUX_API bool save_audio(
    const std::shared_ptr<Kakshya::SoundStreamContainer>& container,
    const std::string& suggested_name = "output.wav");
 
/**
 * @brief Present a native save-file dialog filtered to image formats and save
 *        @p buffer to the chosen path via IOManager::save_image().
 *
 * Blocks until the user confirms or cancels. The encode task is queued
 * asynchronously. Returns false on cancellation, backend error, or if
 * Portal::System is not initialized.
 *
 * @param buffer         Source TextureBuffer to encode.
 * @param suggested_name Filename pre-filled in the dialog name field.
 */
MAYAFLUX_API bool save_image(
    const std::shared_ptr<Buffers::TextureBuffer>& buffer,
    const std::string& suggested_name = "output.png");
 
/**
 * @brief Present a native save-file dialog filtered to image formats and save
 *        @p buffer to the chosen path via IOManager::save_image().
 *
 * Blocks until the user confirms or cancels. The encode task is queued
 * asynchronously. Returns false on cancellation, backend error, or if
 * Portal::System is not initialized.
 *
 * @param buffer         Source TextureBuffer to encode.
 * @param suggested_name Filename pre-filled in the dialog name field.
 * @param options        Format-specific writer options forwarded to IOManager.
 */
MAYAFLUX_API bool save_image(
    const std::shared_ptr<Buffers::TextureBuffer>& buffer,
    const std::string& suggested_name,
    const IO::ImageWriteOptions& options);
 
/**
 * @brief Choose a CSV or TSV destination and save a CompositeContainer.
 *
 * The dialog and write are synchronous. Returns false on cancellation,
 * backend or write failure, or if Portal::System is not initialized.
 *
 * @param container Source container to encode.
 * @param suggested_name Filename pre-filled in the dialog.
 * @return True only when the complete file was written successfully.
 */
MAYAFLUX_API bool save_composite(
    const std::shared_ptr<Kakshya::CompositeContainer>& container,
    const std::string& suggested_name = "output.csv");
 
/**
 * @brief Present a native save-file dialog filtered to 3D model formats and
 *        save @p buffer to the chosen path via IOManager::save_mesh().
 *
 * Blocks until the user confirms or cancels. Synchronous: MeshBuffer's
 * mesh data is always CPU-resident, so there is no download step to queue,
 * unlike save_image/save_volume. Returns false on cancellation, backend
 * error, or if Portal::System is not initialized.
 *
 * @param buffer         Source MeshBuffer to encode.
 * @param suggested_name Filename pre-filled in the dialog name field.
 */
MAYAFLUX_API bool save_mesh(
    const std::shared_ptr<Buffers::MeshBuffer>& buffer,
    const std::string& suggested_name = "output.gltf");
 
/**
 * @brief Present a native save-file dialog filtered to 3D model formats and
 *        save @p buffer to the chosen path via IOManager::save_mesh().
 *
 * @param buffer         Source MeshBuffer to encode.
 * @param suggested_name Filename pre-filled in the dialog name field.
 * @param options        Format-specific writer options forwarded to IOManager.
 */
MAYAFLUX_API bool save_mesh(
    const std::shared_ptr<Buffers::MeshBuffer>& buffer,
    const std::string& suggested_name,
    const IO::ModelWriteOptions& options);
 
/**
 * @brief Present a native save-file dialog filtered to 3D model formats and
 *        save @p network to the chosen path via IOManager::save_mesh().
 *
 * Works directly on the MeshNetwork returned by choose_mesh_network(),
 * whether or not it has ever been wrapped in a MeshNetworkBuffer or
 * rendered: slot data lives on the network's own MeshWriterNodes. Each
 * slot's vertices are baked into world space from its current
 * world_transform, so an exploded or rotated network exports in the pose
 * it is actually in. Blocks until the user confirms or cancels. Returns
 * false on cancellation, backend error, or if Portal::System is not
 * initialized.
 *
 * @param network        Source MeshNetwork to encode.
 * @param suggested_name Filename pre-filled in the dialog name field.
 */
MAYAFLUX_API bool save_mesh(
    const std::shared_ptr<Nodes::Network::MeshNetwork>& network,
    const std::string& suggested_name = "output.gltf");
 
/**
 * @brief Present a native save-file dialog filtered to 3D model formats and
 *        save @p network to the chosen path via IOManager::save_mesh().
 *
 * @param network        Source MeshNetwork to encode.
 * @param suggested_name Filename pre-filled in the dialog name field.
 * @param options        Format-specific writer options forwarded to IOManager.
 */
MAYAFLUX_API bool save_mesh(
    const std::shared_ptr<Nodes::Network::MeshNetwork>& network,
    const std::string& suggested_name,
    const IO::ModelWriteOptions& options);
 
/**
 * @brief Present a native save-file dialog filtered to volume formats and save
 *        @p volume to the chosen path via IOManager::save_volume().
 *
 * Blocks until the user confirms or cancels. The download and encode task
 * are queued asynchronously; this function returns once the path is chosen
 * and the task is enqueued. Returns false on cancellation, backend error,
 * or if Portal::System is not initialized.
 *
 * @param volume         Source VolumeGridBuffer to download and encode.
 * @param suggested_name Filename pre-filled in the dialog name field.
 */
MAYAFLUX_API bool save_volume(
    const std::shared_ptr<Buffers::VolumeGridBuffer>& volume,
    const std::string& suggested_name = "output.vdb");
 
/**
 * @brief Present a native save-file dialog filtered to volume formats and save
 *        @p volume to the chosen path via IOManager::save_volume().
 *
 * Blocks until the user confirms or cancels. The download and encode task
 * are queued asynchronously. Returns false on cancellation, backend error,
 * or if Portal::System is not initialized.
 *
 * @param volume         Source VolumeGridBuffer to download and encode.
 * @param suggested_name Filename pre-filled in the dialog name field.
 * @param options        Writer options forwarded to IOManager.
 */
MAYAFLUX_API bool save_volume(
    const std::shared_ptr<Buffers::VolumeGridBuffer>& volume,
    const std::string& suggested_name,
    const IO::VolumeWriteOptions& options);
 
/**
 * @brief Present a native save-file dialog filtered to Alembic and write
 *        every source once via IOManager::save_spatial_snapshot().
 *
 * Blocks until the user confirms or cancels. The write itself is queued
 * asynchronously; this function returns once the path is chosen and the
 * task is enqueued. Returns false on cancellation, backend error, or if
 * Portal::System is not initialized.
 *
 * @param sources        Streams to write once. Build with
 *                        IO::make_network_geometry_source() or a
 *                        hand-written IO::SpatialCaptureSource.
 * @param suggested_name Filename pre-filled in the dialog name field.
 */
MAYAFLUX_API bool save_spatial(
    std::vector<IO::SpatialCaptureSource> sources,
    const std::string& suggested_name = "output.abc");
 
/**
 * @brief Retrieves the global IOManager instance for file loading and buffer management
 * @return Shared pointer to the IOManager instance
 *
 * Provides access to the central IOManager responsible for all file loading operations,
 * container management, and buffer integration. This is the primary interface for
 * performing file I/O tasks within the MayaFlux engine.
 */
MAYAFLUX_API std::shared_ptr<IO::IOManager> get_io_manager();
 
}