Infinity::Types::Containers::Array3D< T > Class Template Reference

Three-dimensional array container for volumetric data in procedural generation. More...

#include <Array3D.hpp>

Inheritance diagram for Infinity::Types::Containers::Array3D< T >:

Collaboration diagram for Infinity::Types::Containers::Array3D< T >:

Public Member Functions
	Array3D ()
	Default constructor.
	Array3D (size_t width, size_t height, size_t depth)
	Constructs a 3D array with specified dimensions.
	Array3D (size_t width, size_t height, size_t depth, Array< T > data)
	Constructs a 3D array from existing Array data with specified dimensions.
	Array3D (size_t width, size_t height, size_t depth, T *data)
	Constructs a 3D array by copying from a raw data pointer.
	Array3D (size_t width, size_t height, size_t depth, const std::vector< T > &data)
	Constructs a 3D array from a std::vector with specified dimensions.
virtual	~Array3D ()
	Destructor.
std::unique_ptr< Core::Base >	clone () const override
const Infinity::Types::TypeID &	typeId () const override
	Gets the TypeID for this Array3D type.
size_t	width () const noexcept
	Gets the width (number of columns, X dimension) of the 3D array.
size_t	height () const noexcept
	Gets the height (number of rows, Y dimension) of the 3D array.
size_t	depth () const noexcept
	Gets the depth (number of layers, Z dimension) of the 3D array.
T &	at (size_t x, size_t y, size_t z)
	Accesses element at 3D coordinates.
const T &	at (size_t x, size_t y, size_t z) const
	Accesses element at 3D coordinates (const).
virtual size_t	dimensions () const noexcept override
	Gets the number of dimensions in this container.
void	resize (size_t width, size_t height, size_t depth)
	Resizes the 3D array to new dimensions.
Public Member Functions inherited from Infinity::Types::Containers::Array< T >
	Array ()
	Default constructor.
	Array (size_t size)
	Constructs an array with specified size.
	Array (const T *data, size_t size)
	Constructs an array by copying data from a raw pointer.
	Array (const std::vector< T > &data)
	Constructs an array from a std::vector.
	Array (Core::span< T > data)
	Constructs an array from a span.
	Array (const Array &other)
	Copy constructor.
	Array (Array &&other) noexcept
	Move constructor.
virtual	~Array ()
	Destructor.
Array &	operator= (const Array &rhs)
	Copy assignment operator.
Array &	operator= (Array &&rhs) noexcept
	Move assignment operator.
virtual const Infinity::Types::TypeID &	elementTypeId () override
	Gets the TypeID for the element type.
void	copy (const T *data, size_t count)
	Replaces array contents by copying from raw data.
T &	operator[] (size_t index)
	Accesses element at specified index (unchecked).
const T &	operator[] (size_t index) const
	Accesses element at specified index (unchecked, const).
T &	at (size_t index)
	Accesses element at specified index (checked).
const T &	at (size_t index) const
	Accesses element at specified index (checked, const).
void	push_back (const T &value)
	Appends an element to the end of the array.
template<typename... Args>
void	emplace_back (Args &&... args)
	Constructs and appends an element in-place.
void	insert (size_t index, const T &value)
	Inserts an element at the specified position.
void	erase (size_t index)
	Removes the element at the specified position.
void	reserve (size_t capacity)
	Reserves capacity for at least the specified number of elements.
virtual void	resize (size_t newSize) override
	Resizes the array to contain the specified number of elements.
void	shrink_to_fit ()
	Reduces capacity to match the current size.
void	clear () noexcept
	Removes all elements from the array.
virtual bool	containsData () const override
	Checks if the array contains Core::Data-derived types.
virtual bool	containsValues () const override
	Checks if the array contains plain value types.
virtual std::shared_ptr< Core::Data >	dataAt (size_t index) override
	Gets a type-erased Data pointer to the element at the specified index.
virtual std::shared_ptr< const Core::Data >	dataAt (size_t index) const override
	Gets a const type-erased Data pointer to the element at the specified index.
virtual void	setData (size_t index, const Core::Data &data) override
	Sets an element from type-erased Data.
T *	data ()
	Gets a pointer to the underlying data array.
const T *	data () const
	Gets a const pointer to the underlying data array.
T *	releaseData ()
	Releases ownership of the underlying data array.
T &	front ()
	Accesses the first element.
const T &	front () const
	Accesses the first element (const).
T &	back ()
	Accesses the last element.
const T &	back () const
	Accesses the last element (const).
size_t	size () const noexcept override
	Gets the number of elements in the array.
size_t	capacity () const noexcept
	Gets the current capacity.
bool	empty () const noexcept
	Checks if the array is empty.
virtual void *	pointer (size_t index) override
	Gets a void pointer to the element at the specified index.
virtual const void *	pointer (size_t index) const override
	Gets a const void pointer to the element at the specified index.
iterator	begin () noexcept
	Returns an iterator to the beginning.
iterator	end () noexcept
	Returns an iterator to the end.
const_iterator	begin () const noexcept
	Returns a const iterator to the beginning.
const_iterator	end () const noexcept
	Returns a const iterator to the end.
reverse_iterator	rbegin () noexcept
	Returns a reverse iterator to the beginning.
reverse_iterator	rend () noexcept
	Returns a reverse iterator to the end.
const_reverse_iterator	rbegin () const noexcept
	Returns a const reverse iterator to the beginning.
const_reverse_iterator	rend () const noexcept
	Returns a const reverse iterator to the end.
Public Member Functions inherited from Infinity::Types::Containers::ArrayBase
	ArrayBase ()
	ArrayBase (const ArrayBase &other)
virtual	~ArrayBase ()=default
	Virtual destructor.
Public Member Functions inherited from Infinity::Types::Core::Data
	Data ()
	Data (const Data &other)
	Data (Data &&other)
Data &	operator= (const Data &other)
Data &	operator= (Data &&other)
std::unique_ptr< Base >	clone () const override
virtual	~Data ()
	Virtual destructor.
bool	hasProperty (const std::string &key) const
template<typename T >
void	setProperty (const std::string &key, T &&value)
	Sets a typed property value.
template<typename T >
void	setProperty (const std::string &key, const T &value)
	Sets a typed property value.
void	setProperty (const std::string &key, PropertyValue &&value)
	Sets a typed property value.
const PropertyValue &	getProperty (const std::string &key) const
	Gets a property value without type checking.
template<typename T >
const T &	getProperty (const std::string &key) const
	Gets a typed property value.
void	removeProperty (const std::string &key)
Public Member Functions inherited from Infinity::Types::Core::Base
virtual	~Base ()
	Virtual destructor.
virtual std::istream &	legibleDataRead (std::istream &in) override
	Deserializes the object from a single-line text representation.
virtual std::ostream &	legibleDataWrite (std::ostream &out) const override
	Serializes the object to a single-line text representation.

Friends
class	Infinity::IO::Data::Array3DSerializer< T >

Additional Inherited Members
Public Types inherited from Infinity::Types::Containers::Array< T >
using	iterator = T *
using	const_iterator = const T *
using	reverse_iterator = std::reverse_iterator< iterator >
using	const_reverse_iterator = std::reverse_iterator< const_iterator >
Public Attributes inherited from Infinity::Types::Core::Data
std::unordered_map< std::string, PropertyValue >	properties
	Property storage for arbitrary metadata.
Protected Member Functions inherited from Infinity::Types::Containers::Array< T >
void	swap (Array &other) noexcept
	Swaps the contents with another array.
void	reset () noexcept
	Resets the array to an empty state.
void	_reallocate (size_t newCapacity)
	Reallocates the array with a new capacity.
void	_delete () noexcept
	Deallocates the array's memory.
void	_dealloc ()
	Deallocates the array's memory.
Static Protected Member Functions inherited from Infinity::Types::Containers::Array< T >
static T *	_alloc (size_t size)
	Allocates aligned memory for the specified number of elements.
Protected Attributes inherited from Infinity::Types::Containers::Array< T >
Core::span< T >	_data
	Span wrapping the allocated data.
size_t	_capacity
	Total allocated capacity.
size_t	_size
	Current number of elements.

Detailed Description

template<typename T>
class Infinity::Types::Containers::Array3D< T >

Three-dimensional array container for volumetric data in procedural generation.

Array3D<T> extends Array<T> to provide a 3D voxel grid abstraction with row-major storage. It is the fundamental container for volumetric data in the Infinity Engine, including 3D textures, voxel fields, density volumes, and other spatially-organized 3D data structures.

The class stores elements in row-major order with depth as the outermost dimension, making it cache-friendly for XY-plane traversal. All underlying memory management, alignment, and type system integration is inherited from Array<T>.

Key features:

• 3D indexing with at(x, y, z) for intuitive spatial access
• Type alias for common 3D texture data (Texture3D)
• Inherits all Array<T> capabilities (serialization, iteration, SIMD alignment)
• Seamless integration with ProceduralSystem input/output ports
• Support for both scalar and vector element types

Common use cases in procedural generation:

• 3D noise field storage (Perlin, Simplex, Worley noise volumes)
• Volumetric density fields for marching cubes terrain
• 3D textures for material blending and lookups
• Voxel-based procedural structures
• Signed distance fields (SDFs)
• Flow field and vector field storage
• Atmospheric and fog density volumes
• 3D cellular automata and procedural cave systems

Template Parameters

T	Element type (typically scalar or vector types)

Note

Storage order: element at (x, y, z) is at index (z * width * height) + (y * width) + x

All memory is 64-byte aligned (inherited from Array<T>)

For large volumes, consider memory requirements: width × height × depth × sizeof(T)

Example usage:

// Create a 3D density field for terrain generation
Array3D<float> densityField(128, 128, 128);
for (size_t z = 0; z < densityField.depth(); ++z) {
    for (size_t y = 0; y < densityField.height(); ++y) {
        for (size_t x = 0; x < densityField.width(); ++x) {
            densityField.at(x, y, z) = generateDensity(x, y, z);
        }
    }
}
 
// Use with ProceduralSystem
system->setIn("volume_data", std::move(densityField));
 
// Create a 3D texture for volumetric effects
Texture3D volumeTexture(64, 64, 64);
volumeTexture.at(32, 32, 32) = Math::Vector4ub{255, 255, 255, 128};
 
// 3D noise generation
Array3D<float> noiseVolume(256, 256, 256);
for (size_t z = 0; z < 256; ++z) {
    for (size_t y = 0; y < 256; ++y) {
        for (size_t x = 0; x < 256; ++x) {
            noiseVolume.at(x, y, z) = perlin3D(x * 0.01f, y * 0.01f, z * 0.01f);
        }
    }
}

Constructor & Destructor Documentation

Array3D() [1/5]

template<typename T >

Infinity::Types::Containers::Array3D< T >::Array3D ( )

inline

Default constructor.

Constructs an empty 3D array with zero width, height, and depth.

Array3D() [2/5]

template<typename T >

Infinity::Types::Containers::Array3D< T >::Array3D ( size_t  width, size_t  height, size_t  depth  )

inline

Constructs a 3D array with specified dimensions.

Allocates memory for width × height × depth elements and default-constructs them. Elements are stored in row-major order with depth as the outermost dimension.

Parameters

width	Number of columns (X dimension).
height	Number of rows (Y dimension).
depth	Number of layers (Z dimension).

Note

Total allocated size is width × height × depth × sizeof(T) bytes.

Array3D() [3/5]

template<typename T >

Infinity::Types::Containers::Array3D< T >::Array3D ( size_t  width, size_t  height, size_t  depth, Array< T >  data  )

inline

Constructs a 3D array from existing Array data with specified dimensions.

Takes ownership of the provided Array's data and interprets it as a 3D grid.

Parameters

width	Number of columns (X dimension).
height	Number of rows (Y dimension).
depth	Number of layers (Z dimension).
data	Array containing width × height × depth elements.

Warning

The data array must contain exactly width × height × depth elements.

Array3D() [4/5]

template<typename T >

Infinity::Types::Containers::Array3D< T >::Array3D ( size_t  width, size_t  height, size_t  depth, T *  data  )

inline

Constructs a 3D array by copying from a raw data pointer.

Allocates new memory and copies width × height × depth elements from the pointer.

Parameters

width	Number of columns (X dimension).
height	Number of rows (Y dimension).
depth	Number of layers (Z dimension).
data	Pointer to source data (must contain at least width × height × depth elements).

Array3D() [5/5]

template<typename T >

Infinity::Types::Containers::Array3D< T >::Array3D ( size_t  width, size_t  height, size_t  depth, const std::vector< T > &  data  )

inline

Constructs a 3D array from a std::vector with specified dimensions.

Allocates memory and copies all elements from the vector, interpreting them as a 3D grid with the specified dimensions.

Parameters

width	Number of columns (X dimension).
height	Number of rows (Y dimension).
depth	Number of layers (Z dimension).
data	Vector containing width × height × depth elements.

Warning

The vector must contain exactly width × height × depth elements.

~Array3D()

template<typename T >

virtual Infinity::Types::Containers::Array3D< T >::~Array3D ( )

inlinevirtual

Destructor.

Properly destroys all elements and deallocates memory (inherited from Array<T>).

Member Function Documentation

at() [1/2]

template<typename T >

T & Infinity::Types::Containers::Array3D< T >::at ( size_t  x, size_t  y, size_t  z  )

inline

Accesses element at 3D coordinates.

Provides intuitive 3D indexing into the row-major storage with depth as the outermost dimension.

Parameters

x	Column index (0 to width-1).
y	Row index (0 to height-1).
z	Layer index (0 to depth-1).

Returns

Reference to the element at (x, y, z).

Note

Elements are stored as: index = (z * width * height) + (y * width) + x

Currently does not perform bounds checking.

at() [2/2]

template<typename T >

const T & Infinity::Types::Containers::Array3D< T >::at ( size_t  x, size_t  y, size_t  z  ) const

inline

Accesses element at 3D coordinates (const).

Provides intuitive 3D indexing into the row-major storage with depth as the outermost dimension.

Parameters

x	Column index (0 to width-1).
y	Row index (0 to height-1).
z	Layer index (0 to depth-1).

Returns

Const reference to the element at (x, y, z).

Note

Elements are stored as: index = (z * width * height) + (y * width) + x

Currently does not perform bounds checking.

clone()

template<typename T >

std::unique_ptr< Core::Base > Infinity::Types::Containers::Array3D< T >::clone ( ) const

inlineoverridevirtual

Reimplemented from Infinity::Types::Containers::Array< T >.

depth()

template<typename T >

size_t Infinity::Types::Containers::Array3D< T >::depth ( ) const

inlinenoexcept

Gets the depth (number of layers, Z dimension) of the 3D array.

Returns

Depth of the array.

dimensions()

template<typename T >

virtual size_t Infinity::Types::Containers::Array3D< T >::dimensions ( ) const

inlineoverridevirtualnoexcept

Gets the number of dimensions in this container.

Returns

Always returns 3 for Array3D (three-dimensional).

Reimplemented from Infinity::Types::Containers::Array< T >.

height()

template<typename T >

size_t Infinity::Types::Containers::Array3D< T >::height ( ) const

inlinenoexcept

Gets the height (number of rows, Y dimension) of the 3D array.

Returns

Height of the array.

resize()

template<typename T >

void Infinity::Types::Containers::Array3D< T >::resize ( size_t  width, size_t  height, size_t  depth  )

inline

Resizes the 3D array to new dimensions.

Reallocates the array to hold width × height × depth elements. If the new size is larger, new elements are default-constructed. If smaller, excess elements are destroyed. Existing data is preserved where possible (up to min of old/new dimensions).

Parameters

width	New number of columns (X dimension).
height	New number of rows (Y dimension).
depth	New number of layers (Z dimension).

Note

This completely replaces the array contents. Elements are stored in row-major order with depth as the slowest-changing dimension.

typeId()

template<typename T >

const Infinity::Types::TypeID & Infinity::Types::Containers::Array3D< T >::typeId ( ) const

inlineoverridevirtual

Gets the TypeID for this Array3D type.

Returns

TypeID identifying this Array3D<T> specialization.

Reimplemented from Infinity::Types::Containers::Array< T >.

width()

template<typename T >

size_t Infinity::Types::Containers::Array3D< T >::width ( ) const

inlinenoexcept

Gets the width (number of columns, X dimension) of the 3D array.

Returns

Width of the array.

Friends And Related Symbol Documentation

Infinity::IO::Data::Array3DSerializer< T >

template<typename T >

friend class Infinity::IO::Data::Array3DSerializer< T >

friend