read_dense_scalar()

bool MayaFlux::IO::Detail::VDBArchive::read_dense_scalar	(	size_t	index,
		const glm::ivec3 &	region_min,
		const glm::uvec3 &	resolution,
		float	background,
		std::vector< float > &	out,
		bool *	precision_lost = nullptr
	)		const

Materialize a scalar grid's cells over an explicit region.

region_min and resolution are expressed in the grid's own voxel-index space — the same space active_min/active_max in grid_summary() use. A cell not covered by any active leaf, and a cell whose index falls outside the region entirely, both take background. Output is resized to resolution.x*y*z elements and written x-fastest, z-slowest, matching Lattice3D and VolumeField's convention.

A grid whose leaf value type is not float is converted per-element via MayaFlux::try_convert; check grid_summary().narrowed beforehand to know whether that happened at all, or pass precision_lost to learn whether it happened losslessly. Every element that round-trips through float and back to the source type unchanged leaves it false; a single element that doesn't sets it true for the whole call. half is the one source type never marked lossy — float has strictly more precision in both exponent and mantissa, so widening it is always exact.

Parameters

precision_lost

Set to whether any narrowed element lost precision. Cleared to false at the start of the call if non-null; left untouched by a null pointer.

Returns

False if index is out of range, the grid is vector-typed, or resolution has a zero axis. Call last_error() for detail.

Definition at line 734 of file VDBArchive.cpp.

{
    if (!m_state->read_file_open || index >= m_state->read_file.num_grids) {
        m_last_error = "read_dense_scalar: grid index out of range";
        return false;
    }
    if (resolution.x == 0 || resolution.y == 0 || resolution.z == 0) {
        m_last_error = "read_dense_scalar: zero resolution";
        return false;
    }
 
    const tvdb_grid_t& grid = m_state->read_file.grids[index];
    const tvdb_value_type_t vt = leaf_value_type(grid);
 
    if (is_vector_type(vt)) {
        const char* name = tvdb_grid_name(&m_state->read_file, index);
        m_last_error = "read_dense_scalar: grid '" + std::string(name ? name : "") + "' is vector-typed";
        return false;
    }
    const size_t elem_size = tvdb_value_type_size(vt);
    if (elem_size == 0) {
        m_last_error = "read_dense_scalar: grid has an unsupported leaf value type";
        return false;
    }
 
    if (precision_lost) {
        *precision_lost = false;
    }
 
    out.assign(static_cast<size_t>(resolution.x) * resolution.y * resolution.z, background);
 
    DenseScalarCtx ctx {};
    ctx.region_min = region_min;
    ctx.region_max = region_min + glm::ivec3(resolution);
    ctx.vt = vt;
    ctx.elem_size = elem_size;
    ctx.precision_lost = precision_lost;
    ctx.out = &out;
 
    tvdb_grid_visit_leaves(&grid, dense_scalar_visit, &ctx);
    return true;
}

References elem_size, index, m_last_error, m_state, name, out, precision_lost, region_min, and vt.