UN_DataBuffer.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UN_DataBuffer.h ( UN Library, C++)
 *
 * COMMENTS:
 *      Core functionality for a utility-based node.
 */

#ifndef __UN_DataBuffer_h__
#define __UN_DataBuffer_h__

#include "UN_API.h"
#include "UN_Include.h"


// ============================================================================
/// Vectorized memory buffer that contains data entries for a particular 
/// aspect for a group of items of the same kind in the graph. 
/// Each entry in the buffer holds a piece of data for a single item.
/// For example, a buffer may hold names for the nodes, so each buffer entry
/// holds a name for a single node.
/// This class is templated on the type of the entries it stores.
template <typename T>
class UN_DataBuffer
{
public:
    // Default constructor. Constructs an empty buffer.
    UN_DataBuffer() = default;

    // Constructs a buffer and sets its entry (slot) size to the given number.
    UN_DataBuffer( UN_DataSize size )
    {
        myBuffer.bumpSize(size);
    }

    /// @{ Sets the data value for the entry at a given index.
    void        setData( UN_DataIndex index, const T &value )
                    { myBuffer[ index ] = value; }
    void        setData( UN_DataIndex index, T &&value )
                    { myBuffer[ index ] = std::move(value); }
    /// @}

    /// @{ Returns the data value for the entry at a given index.
    /// Note, this buffer class does not provide a getter method that
    /// returns a mutable (non-const) reference to the underlying data 
    /// to avoid aliasing, which is problematic for threading.
    /// However, it provides stealData() to move the value out of buffer.
    const T &   getDataRef( UN_DataIndex index ) const
                    { return myBuffer[ index ]; }
    const T &   operator[]( UN_DataIndex index) const
                    { return getDataRef( index ); }
    /// @}

    /// Returns a moved value from an entry in a data buffer.
    T           stealData( UN_DataIndex index ) 
                    { return std::move( myBuffer[ index ] ); }

    /// Updates a data entry value in-place inside the data buffer.
    /// For complex data types (eg, dictionaries or arrays) it is faster 
    /// than getting and setting the value (although stealing and setting
    /// back a moved value is comparable). 
    /// This is a convenient and useful idiom, that tries to avoid the buffer 
    /// aliasing issues, that cause problems in multithreading.
    /// Intended usage: 
    ///   updateData(index, [&key, &value](auto &dict) { dict[key] = value; });
    template<typename OP>
    void        updateData( UN_DataIndex index, const OP &op  )
                    { op( myBuffer[ index ] ); }

    /// Adds an entry slot to the data buffer.
    void        addData( UN_DataIndex index, const T& init_value = T() ) 
                    {
                        // Note, currently UN appends to the buffer to extend
                        // it, but this may change in the future. 
                        // This assert is to alert to such change, but can be
                        // safely ignored and removed for this particular
                        // implementation since UT_Array supports insertions.
                        UT_ASSERT( index == myBuffer.size() );
                        myBuffer.insert( init_value, index );
                    }

    /// Appends count copies of the given value.
    void        appendData( const T &value, exint count )
                    {
                        myBuffer.appendMultiple( value, count );
                    }

    /// Appends a span of entries from another buffer.
    void        appendData( const UN_DataBuffer<T> &src,
                            UN_DataIndex start,
                            UN_DataSize size )
                    {
                        UT_ASSERT( start >= 0 && size >= 0 && 
                                   start + size <= src.size() );
                        myBuffer.append( src.myBuffer.data() + start, size );
                    }

    /// Resets the data to an empty buffer.
    void        clear() 
                    { myBuffer.clear(); }

    /// Returns the number of elements held in the data buffer.
    UN_DataSize size() const
                    { return UN_DataSize( myBuffer.size() ); }

    // Grow the buffer if the given size is larger than the current one.
    // Copies the entries if that occurs.
    void        setCapacityIfNeeded( UN_DataSize min_capacity )
                    { myBuffer.setCapacityIfNeeded( min_capacity ); }

    /// Return true if given index is valid.
    bool        isValidIndex( UN_DataIndex index ) const
                    { return myBuffer.isValidIndex( index ); }

private:
    /// The underlying buffer wrapped by this class.
    UT_Array<T>             myBuffer;
};


// ============================================================================
// Data buffer for string data.
#include <UT/UT_StringArray.h>

using UN_StringDataBuffer = UN_DataBuffer<UT_StringHolder>;
using UN_StringArrayDataBuffer = UN_DataBuffer<UT_StringArray>;

// ============================================================================
// Data buffer for numeric data.
using UN_ExintDataBuffer    = UN_DataBuffer<exint>; 
using UN_UintDataBuffer     = UN_DataBuffer<unsigned int>; 
using UN_FloatDataBuffer    = UN_DataBuffer<float>; 

// ============================================================================
// Data buffer for vector data.
#include <UT/UT_Color.h>
#include <UT/UT_Vector3.h>
#include <UT/UT_VectorTypes.h>
//using UN_Vector2FDataBuffer = UN_DataBuffer<UT_Vector2F>; 
using UN_Vector2DDataBuffer = UN_DataBuffer<UT_Vector2D>; 
using UN_Vector2RDataBuffer = UN_DataBuffer<UT_Vector2R>; 
//using UN_Vector3FDataBuffer = UN_DataBuffer<UT_Vector3F>; 
//using UN_Vector3DDataBuffer = UN_DataBuffer<UT_Vector3D>; 
//using UN_Vector3RDataBuffer = UN_DataBuffer<UT_Vector3R>; 

using UN_ColorDataBuffer = UN_DataBuffer<UT_Color>; 


// ============================================================================
/// Data buffer specialization for boolean (bit) values.
// Loosely based on UT_BitArray, but with interface adjusted to UN data buffers.
template <>
class UN_DataBuffer<bool>
{
public:
    // Default constructor. Constructs an empty buffer.
    UN_DataBuffer() = default;

    // Constructs a buffer and sets its entry (slot) size to the given number.
    UN_DataBuffer( UN_DataSize size )
    {
        exint word_size = wordCapacity( size );
        myWordBuffer.bumpSize( word_size );
        myWordBuffer.constant( myZero );
        mySize = size;
    }

    /// Sets the data value for the entry at a given index.
    void setData( UN_DataIndex index, bool value )
    {
        UT_ASSERT_P( index >= 0 && index < mySize );
        BlockType &word = myWordBuffer[ wordIndex(index) ];
        int bit = index.exintValue() & myWordMask;
        word = (BlockType(value) << bit) | (word & ~(BlockType(1) << bit));
    }

    /// Returns the data value for the entry at a given index.
    bool getDataVal( UN_DataIndex index ) const
    {
        UT_ASSERT_P( index >= 0 && index < mySize );
        BlockType word = myWordBuffer[ wordIndex(index) ];
        int bit = index.exintValue() & myWordMask;
        return (word >> bit) & BlockType(1);
    }

    /// Returns the data value for the entry at a given index.
    /// Just a convenience operator that calls the official API method.
    bool operator[]( UN_DataIndex index) const
    {
        return getDataVal( index );
    }

    /// Adds an entry slot to the data buffer.
    void addData( UN_DataIndex index, bool init_value = false )
    {
        // Note, UN always appends new entry slots to the buffer,
        // so we can simplify the implementation here.
        UT_ASSERT( index == mySize );
        if( wordIndex( index ) >= myWordBuffer.size() )
            myWordBuffer.append();
        mySize++;

        setData( index, init_value );
    }

    /// Appends count copies of the given value.
    void appendData( bool value, exint count )
    {
        for( exint i = 0; i < count; i++ )
            addData( UN_DataIndex(mySize), value );
    }

    /// Appends a span of entries from another buffer.
    void appendData( const UN_DataBuffer<bool> &src,
            UN_DataIndex start, UN_DataSize size )
    {
        // TODO: FIXME: optimize this method by copying the whole words,
        //              after shifting them appropriately.
        // TODO: FIXME: look at geo lib and GA_ElementGroup
        //              Groups a bit fields so resemble bool data array
        for( exint i = start, n = start + size; i < n; i++ )
            addData( UN_DataIndex(mySize), src.getDataVal( UN_DataIndex(i) ));
    }

    /// Resets the data to an empty buffer.
    void clear()
    {
        mySize = 0;
        myWordBuffer.clear();
    }

    /// Returns the number of bits held in the data buffer.
    UN_DataSize size() const
    {
        return UN_DataSize( mySize );
    }

    // Grow the buffer if the given size is larger than the current one.
    // Copies the entries if that occurs.
    void setCapacityIfNeeded( UN_DataSize min_capacity )
    {
        myWordBuffer.setCapacityIfNeeded( wordCapacity( min_capacity ));
    }

    /// Return true if given index is valid.
    bool isValidIndex( UN_DataIndex index ) const
    {
        return index >= 0 && index < mySize;
    }


private:
    using BlockType = uint32;
    static constexpr int    myBitsPerWord = sizeof(BlockType)*8;
    static constexpr int    myWordShift = SYS_LOG2F(myBitsPerWord);
    static constexpr int    myWordMask = (1 << myWordShift) - 1;
    static constexpr BlockType    myZero = 0;

    // Returns the word number in which the given bit would be.
    static inline exint     wordIndex(exint bit_index)
                                { return (bit_index >> myWordShift); }

    // Retusns the word capacity given the bit capacity.
    exint wordCapacity( UN_DataSize bit_capacity )
    {
        return (bit_capacity > 0) ?
            (bit_capacity.exintValue() - 1) / myBitsPerWord + 1 : 0;
    }

private:
    UT_Array<BlockType>     myWordBuffer;
    exint                   mySize = 0;
};

using UN_BoolDataBuffer = UN_DataBuffer<bool>;


// ============================================================================
// Data buffer for generic values.
#include <UT/UT_OptionEntry.h>

class UN_ValueHandle 
{
public:
     UN_ValueHandle() = default;
    ~UN_ValueHandle() = default;
     UN_ValueHandle( UN_ValueHandle const& other ) 
         : myOptionPtr( other.valuePtr() ?
                other.valuePtr()->clone() : UT_OptionEntryPtr() ) {}
     UN_ValueHandle( UN_ValueHandle && other ) = default;
     UN_ValueHandle( UT_OptionEntryPtr &&value )
         : myOptionPtr( std::move(value) ) {}

     UN_ValueHandle& operator=( UN_ValueHandle const& other ) 
        { 
            myOptionPtr = other.valuePtr() ? 
                other.valuePtr()->clone() : UT_OptionEntryPtr();
            return *this; 
        }
    UN_ValueHandle& operator=( UN_ValueHandle && other ) = default;

    const UT_OptionEntryPtr &   valuePtr() const { return myOptionPtr; }
    UT_OptionEntryPtr &         valuePtr()       { return myOptionPtr; }

private:
    UT_OptionEntryPtr           myOptionPtr;
};

using UN_ValueDataBuffer = UN_DataBuffer< UN_ValueHandle >;


// ============================================================================
// Data buffer for metadata dictionaries.
#include <UT/UT_Options.h>

using UN_MetadataHolder = UT_OptionsHolder;
using UN_MetaDataBuffer = UN_DataBuffer< UN_MetadataHolder >;

// ============================================================================
// Data buffer for ID lists.
#include "UN_Include.h"

using UN_NodeIDsDataBuffer = UN_DataBuffer< UN_NodeIDList >;
using UN_WireIDsDataBuffer = UN_DataBuffer< UN_WireIDList >;

// ============================================================================
/// Utility functions that operate on data buffers.
namespace UN_DataBufferUtils
{
    /// Sets the value of the data entry in the buffer.
    template<typename V, typename B>
    static inline void
    setData( B &buffer, UN_DataIndex index, const V &value )
    {
        if( index )
            buffer.setData( index, value );
    }

    /// Sets the value of the data entry in the buffer, 
    /// allowing for move-assign optimization.
    template<typename V, typename B>
    static inline void
    setData( B &buffer, UN_DataIndex index, V &&value )
    {
        if( index )
            buffer.setData( index, std::forward<V>(value) );
    }

    /// Returns a const ref to an entry in the data buffer.
    template<typename V, typename B>
    static inline const V &
    getDataRef( const B &buffer, UN_DataIndex index, const V &default_value ) 
    {
        if( index )
            return buffer.getDataRef( index );

        return default_value;
    }

    /// Returns a value constructed from an entry in the data buffer.
    /// This is useful when the type returned here differs from 
    /// the underlying entry type.
    /// In particular, this is needed for UN_BoolDataBuffer whose underlying 
    /// entries are bits (for which we can't return a const reference) 
    /// while here we are returning bool (byte).
    template<typename V, typename B>
    inline V 
    getDataVal( const B &buffer, UN_DataIndex index, const V &default_value ) 
    {
        if( index )
            return V(buffer.getDataVal( index ));

        return V(default_value);
    }

    /// Helper function to return a value moved from an entry in a data buffer.
    template<typename V, typename B>
    static inline V 
    stealData( B &buffer, UN_DataIndex index, const V &default_value )
    {
        if( index )
            return buffer.stealData( index );

        return V( default_value );
    }

    /// Helper function to update an entry value in the data buffer.
    /// It updates a data value in-place in the data buffer, 
    /// which for complex data values (eg, dictionaries or arrays) is faster 
    /// than getting and setting the value (although stealing and setting
    /// may be comparable). This is a convenient and useful idiom, that
    /// tries to avoid the buffer data aliasing issues.
    /// Intended usage: 
    ///   updateData(buff, id, [&key, &value](auto &x) { x[key] = value; });
    template<typename OP, typename B>
    static inline void
    updateData( B &buffer, UN_DataIndex index, const OP &op  )
    {
        if( index )
            buffer.updateData( index, op );
    }
};

// ============================================================================
#endif