download_volume()

std::optional< Kakshya::VolumeData > MayaFlux::IO::download_volume	(	const std::shared_ptr< Buffers::VolumeGridBuffer > &	volume,
		const std::vector< std::string > &	field_names = {}
	)

Download named fields from a GPU-resident volume into host VolumeData.

Performs one blocking GPU->host transfer per field via VolumeGridBuffer::read_field, reading the current read slot of each. The calling thread must have command queue access, and the call costs a full round trip at each field's byte size. Not for per-frame use on the graphics thread.

Fields with stride sizeof(float) land as scalars. Fields with stride sizeof(glm::vec4) are read into scratch storage and gathered into glm::vec3, discarding the padding component the GPU layout requires and nothing reads. That gather costs a second allocation at four thirds the output size, which is the price of doing the pack on the host.

Any other stride is unrepresentable in VolumeData and is skipped with an error. A named field that was never declared is likewise skipped.

Parameters

volume	Volume to read from.
field_names	Fields to download. Empty means every declared field, in declaration order.

Returns

Populated VolumeData, or std::nullopt if nothing was downloaded or the result failed is_consistent().

Definition at line 18 of file VolumeTransfer.cpp.

{
    if (!volume) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_volume: null volume");
        return std::nullopt;
    }
 
    const auto names = field_names.empty() ? volume->get_field_names() : field_names;
    if (names.empty()) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_volume: volume declares no fields");
        return std::nullopt;
    }
 
    Kakshya::VolumeData result;
    result.lattice = volume->get_lattice();
    result.fields.reserve(names.size());
 
    const size_t cells = result.cell_count();
 
    std::vector<std::string> batch_names;
    std::vector<std::pair<void*, size_t>> batch_dsts;
    std::vector<std::vector<glm::vec4>> padded;
 
    batch_names.reserve(names.size());
    batch_dsts.reserve(names.size());
    padded.reserve(names.size());
 
    for (const auto& name : names) {
        if (!volume->has_field(name)) {
            MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
                "download_volume: no field named '{}', skipped", name);
            continue;
        }
 
        const size_t stride = volume->get_field_stride(name);
 
        Kakshya::VolumeField field;
        field.name = name;
        field.semantics = volume->get_field_semantics(name);
 
        if (stride == sizeof(float)) {
            field.values = std::vector<float>(cells);
            result.fields.push_back(std::move(field));
            auto& values = *result.fields.back().as_scalar();
            batch_names.push_back(name);
            batch_dsts.emplace_back(values.data(), cells * sizeof(float));
            continue;
        }
 
        if (stride == sizeof(glm::vec4)) {
            field.values = std::vector<glm::vec3>(cells);
            result.fields.push_back(std::move(field));
            auto& scratch = padded.emplace_back(cells);
            batch_names.push_back(name);
            batch_dsts.emplace_back(scratch.data(), cells * sizeof(glm::vec4));
            continue;
        }
 
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_volume: field '{}' has stride {}, which VolumeData "
            "cannot represent (expected {} or {})",
            name, stride, sizeof(float), sizeof(glm::vec4));
    }
 
    volume->read_fields(batch_names, batch_dsts);
 
    size_t vector_index = 0;
    for (auto& field : result.fields) {
        auto* out = field.as_vector();
        if (!out) {
            continue;
        }
        const auto& src = padded[vector_index++];
        for (size_t i = 0; i < cells; ++i) {
            (*out)[i] = glm::vec3(src[i]);
        }
    }
 
    if (result.fields.empty()) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_volume: no field was downloaded");
        return std::nullopt;
    }
 
    if (!result.is_consistent()) {
        MF_ERROR(Journal::Component::IO, Journal::Context::FileIO,
            "download_volume: resulting VolumeData failed is_consistent()");
        return std::nullopt;
    }
 
    MF_DEBUG(Journal::Component::IO, Journal::Context::FileIO,
        "download_volume: {}x{}x{} lattice, {} of {} fields",
        result.lattice.resolution.x, result.lattice.resolution.y,
        result.lattice.resolution.z, result.fields.size(), names.size());
 
    return result;
}

References MayaFlux::Kakshya::VolumeData::cell_count(), MayaFlux::Kakshya::VolumeData::fields, MayaFlux::Journal::FileIO, MayaFlux::Journal::IO, MayaFlux::Kakshya::VolumeData::is_consistent(), MayaFlux::Kakshya::VolumeData::lattice, MF_DEBUG, MF_ERROR, name, MayaFlux::Kakshya::VolumeField::name, out, MayaFlux::Kinesis::Lattice3D::resolution, MayaFlux::Kakshya::VolumeField::semantics, src, values, and MayaFlux::Kakshya::VolumeField::values.

Referenced by MayaFlux::IO::VolumeCapture::capture_frame(), MayaFlux::IO::IOManager::save_volume(), and save_volume().

Here is the call graph for this function:

Here is the caller graph for this function: