APEX_Types.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:        APEX_Types.h (APEX Library, C++)
 *
 * COMMENTS:
 */

#ifndef __APEX_TYPES_H__
#define __APEX_TYPES_H__

#include "APEX_API.h"
#include "APEX_Include.h"

#include <UT/UT_Array.h>
#include <UT/UT_ArrayMap.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_Assert.h>
#include <UT/UT_Debug.h>
#include <UT/UT_StringHolder.h>
#include <SYS/SYS_StaticAssert.h>
#include <SYS/SYS_Compiler.h>
#include <SYS/SYS_Types.h>
#include <SYS/SYS_TypeTraits.h>

#include <new>
#include <typeindex>
#include <typeinfo>
#include <utility>

#include <stddef.h>

namespace apex
{

class APEX_Buffer;
class APEX_Graph;
class APEX_TypeDefinitionBase;

APEX_API UT_ArrayStringMap<const APEX_TypeDefinitionBase *> &APEXtypeDefinitions();

static constexpr UT_StringLit theUndefTypeName  = "undefined";
static constexpr UT_StringLit theVariadicPrefix = "VariadicArg<";
static constexpr UT_StringLit theVariadicFormat = "VariadicArg<{}>";
static constexpr char         theInplacePortPrefix[] = "*";
static constexpr char         theSparePortPrefix[] = "+";
static constexpr char         theConditionalInplacePortPrefix[] = "-";
static constexpr UT_StringLit theSparePortName = "__spare__";
static constexpr UT_StringLit theRunDataPortName = "rundata";

class APEX_TypeDefinitionBase
{
public:
    virtual ~APEX_TypeDefinitionBase() {}

    /// Return the size of a single instance of the type, or 0 if the type is not well-defined (i.e. a void).
    virtual size_t sizeT() const = 0;

    /// Return a human-readable string representing the type.
    virtual const UT_StringRef &repr() const = 0;
    /// Allocate a resizable array of the type. The current implementation uses a UT_Array behind-the-scenes, however
    /// the implementation is type-erased to allow flexibility.
    virtual void *allocate(exint size) const = 0;
    /// Append a default-constructed instance to the array previously allocated by @ref allocate. If no allocation could be performed,
    /// return -1.
    virtual exint append(void *mem) const = 0;
    /// Reset the instance of this type (member of buffer created in @ref allocate) to a default value if possible.
    virtual void clear(void *mem) const = 0;
    /// Free a resizable array created by @ref allocate.
    virtual void deallocate(void *mem) const = 0;
    /// Get a pointer to the @p{index}-th value in the resizable array created by @ref allocate stored at @p mem.
    virtual void *getPtrAtIndex(void *mem, exint index) const = 0;

    virtual bool compile(APEX_Buffer *buffer, APEX_Graph *graph, APEX_PortID port) const = 0;
    /// Copy the value at @p val to @p mem.
    virtual void setData(void *mem, const void *val) const = 0; 
    /// If this is a compound type (such as variadics), return the type definition for the contained type.
    virtual const APEX_TypeDefinitionBase *subTypeDef() const = 0;
    /// Return the RTTI information for the contained type.
    virtual std::type_index typeIndex() const = 0;
    /// Return whether the type is copy-assignable (i.e. can @ref setData function).
    virtual bool isCopyable() const = 0;
    /// Return whether the type is an array
    virtual bool isArray() const { return false; }
    /// Return whether the type is a variadic arg
    virtual bool isVariadic() const { return false; }
    /// Return whether the type is a handle to some shared data (i.e. geometry)
    virtual bool isHandle() const { return false; }
};

/// Compile-time information about the default initialization to use for a type visible to the APEX type system.
template <typename T>
struct APEX_TypeDefault
{
    /// Return a default value for the type.
    static T value() { return T(); }

    /// If this member is missing or false in a specialization, the default value is assumed to be
    /// something other than T(), and any code that implicitly relies on that being the case will
    /// static assert.
    static constexpr bool isDefaultConstructing = true;
};

template <>
struct APEX_TypeDefault<Vector2>
{
    static Vector2 value() { return Vector2(0.0, 0.0); }
};

template <>
struct APEX_TypeDefault<Vector3>
{
    static Vector3 value() { return Vector3(0.0, 0.0, 0.0); }
};

template <>
struct APEX_TypeDefault<Vector4>
{
    static Vector4 value() { return Vector4(0.0, 0.0, 0.0, 0.0); }
};

template <>
struct APEX_TypeDefault<Matrix3>
{
    static Matrix3 value() { return Matrix3(1.0); }
};

template <>
struct APEX_TypeDefault<Matrix4>
{
    static Matrix4 value() { return Matrix4(1.0); }
};

namespace detail
{

template <typename T, typename = void>
struct APEX_TypeDefaultIsSpecialized : SYS_TrueType
{
};

template <typename T>
struct APEX_TypeDefaultIsSpecialized<
        T,
        SYS_Void_t<decltype(APEX_TypeDefault<T>::isDefaultConstructing)>>
    : SYS_BoolConstant<APEX_TypeDefault<T>::isDefaultConstructing == false>
{
};

template <typename T>
constexpr inline auto APEX_TypeDefaultIsSpecialized_v = APEX_TypeDefaultIsSpecialized<T>::value;

}

template <typename T>
static inline void *
allocateT(exint size)
{
    auto *arr = new UT_Array<T>(size);
    if constexpr (SYS_IsPod_v<T>)
    {
        arr->setSizeNoInit(size);
        arr->constant(APEX_TypeDefault<T>::value());
    }
    else if constexpr (std::is_move_constructible_v<T>)
    {
        arr->setCapacity(size);
        for (exint i = 0; i < size; ++i)
            arr->emplace_back(APEX_TypeDefault<T>::value());
    }
    else
    {
        SYS_STATIC_ASSERT_MSG(
                !detail::APEX_TypeDefaultIsSpecialized_v<T>, "A move constructor must be declared on a "
                                                     "type with an explicit APEX default value.");
        arr->setSize(size);
    }
    return arr;
}

template <typename T>
class APEX_TypeTraits
{
public:
    /// Called to allocate a @c UT_Array<T> of length @p size.
    static void *allocate(exint size) { return allocateT<T>(size); }
    /// Called for each non-subport usage of a type with the buffer, graph and allocated port.
    ///
    /// Returns whether or not compilation was successful -- if it returns false, then compilation
    /// is aborted. Error messages can be added into the passed graph with addError. For types which
    /// handle their own subports (like VariadicArgs), validity of those subports must be checked
    /// here; callbacks can do the same thing (usually with __spare__ ports) in their compile
    /// callback.
    static bool compile(APEX_Buffer *buffer, APEX_Graph *graph, APEX_PortID port) { return true; }
    /// Given an initialized instance of `T`, reset it to the default state.
    static void clear(T *mem)
    {
        // If we can assign the type to its default, use that. Despite the name of the type trait,
        // this also catches copy assign operators (it's defined as whether assigning from an rvalue
        // compiles, which is precisely what the guarded statement does -- there is no need to allow
        // adding extra types to the condition as anything not std::is_move_assignable_v will not
        // compile)
        if constexpr (std::is_move_assignable_v<T>)
        {
            *mem = APEX_TypeDefault<T>::value();
        }
        // If the type is not assignable, then destroy the old object and construct a new one in its
        // place. If the destructor is trivial or the type was marked POD with SYS_DECLARE_IS_POD
        // then the destructor call is skipped. Note that the apparent use of a move constructor
        // here is not what it seems: due to the new rvalue semantics in C++17 (aka "guaranteed copy
        // elision") the call to value() directly initializes the data in `mem` (almost as if it
        // took a hidden destination pointer) so no temporary is ever made. This trick is not
        // possible in the various UT_Array-dependent parts of the APEX type system, as they do not
        // expose any API to manually call the constructors for new elements.
        else
        {
            if constexpr (!std::is_trivially_destructible_v<T> && !SYS_IsPod_v<T>)
                mem->~T();
            new (static_cast<void *>(mem)) T(APEX_TypeDefault<T>::value());
        }
    }
    static bool isHandle() { return false; }
};

template <typename T, typename = void>
struct APEX_IsCompoundType : SYS_FalseType
{
};

/// Check if an APEX type wraps another type (for example, @ref VariadicArg)
template <typename T>
struct APEX_IsCompoundType<T, SYS_Void_t<typename T::value_type>> : SYS_TrueType
{
};

// The idea behind this overload is to support callbacks that perform
//  'graph-compile-time' type resolution, resolving the underlying types
//  connected data. This class enables higher level tooling to treat
//  these callbacks and their signatures in the same way as well-defined
//  types whilst also being able to detect whether special allocation or
//  compilation steps are necessary.
//  For an example see the APEX_CopyArg callback in APEX_Callback.h
class APEX_VoidTypeDefinition : public APEX_TypeDefinitionBase
{
public:
    APEX_VoidTypeDefinition()
        : myTypeName("void")
        , mySubTypeDef(nullptr)
        , myTypeIndex(std::type_index(typeid(void)))
    {
        auto key = typeid(void).name();
        UT_ASSERT(APEXtypeDefinitions().contains(key)
                  ? APEXtypeDefinitions()[key]->repr() == myTypeName
                  : true);
        APEXtypeDefinitions()[key] = this;
    }

    ~APEX_VoidTypeDefinition() override {}

    size_t sizeT() const override { return 0; }
    const UT_StringRef &repr() const override { return myTypeName.asRef(); }
    void *allocate(exint size) const override { return nullptr; }
    void clear(void *mem) const override {}
    exint append(void *mem) const override { return -1; }
    void deallocate(void *mem) const override {}
    void *getPtrAtIndex(void *mem, exint index) const override { return nullptr; }
    void setData(void *mem, const void *val) const override {}
    bool compile(APEX_Buffer *buffer, APEX_Graph *graph, APEX_PortID port) const override { return true; }
    const APEX_TypeDefinitionBase *subTypeDef() const override { return mySubTypeDef; }
    std::type_index typeIndex() const override { return myTypeIndex; }
    bool isCopyable() const override { return false; };

private:
    const UT_StringLit myTypeName;
    const APEX_TypeDefinitionBase *mySubTypeDef;
    std::type_index myTypeIndex;
};

template <typename>
struct APEX_IsArrayType : public SYS_FalseType
{
};

template <typename T> class ApexArray;

template <typename T>
struct APEX_IsArrayType<ApexArray<T>> : public SYS_TrueType
{
};

template <typename>
struct APEX_IsVariadicType : public SYS_FalseType
{
};


template <typename T>
struct APEX_IsVariadicType<VariadicArg<T>> : public SYS_TrueType
{
};

template <typename T>
class APEX_TypeDefinition : public APEX_TypeDefinitionBase
{
public:
    APEX_TypeDefinition(const UT_StringLit &&type_name)
        : myTypeName(type_name)
        , mySubTypeDef(nullptr)
        , myTypeIndex(std::type_index(typeid(T)))
    {
        // UTdebugPrint(type_name, std::is_copy_assignable_v<T>, std::is_copy_constructible_v<T>);
        auto key = typeid(T).name();
        UT_ASSERT(APEXtypeDefinitions().contains(key)
                  ? APEXtypeDefinitions()[key]->repr() == myTypeName
                  : true);
        if (!APEXtypeDefinitions().contains(key))
            APEXtypeDefinitions()[key] = this;
        if constexpr (APEX_IsCompoundType<T>::value)
        {
            auto sub_key = typeid(typename T::value_type).name();
            if (APEXtypeDefinitions().contains(sub_key))
            {
                mySubTypeDef = APEXtypeDefinitions()[sub_key];
            }
        }
    }

    ~APEX_TypeDefinition() override {}

    typedef T value_type;

    const UT_StringRef &repr() const override { return myTypeName.asRef(); }

    size_t sizeT() const override { return sizeof(T); }

    /// Return number of definitions present in the provided memory
    /// block.
    exint entries(void *mem) const
    {
        UT_Array<T> *buffer_arr = reinterpret_cast<UT_Array<T> *>(mem);
        if (buffer_arr) return buffer_arr->entries();
        return 0;
    }

    void *allocate(exint size) const override
    {
        return APEX_TypeTraits<T>::allocate(size);
    }

    void clear(void *mem) const override
    {
        APEX_TypeTraits<T>::clear(reinterpret_cast<T *>(mem));
    }

    exint append(void *mem) const override
    {
        UT_Array<T> *buffer_arr = reinterpret_cast<UT_Array<T> *>(mem);
        exint index = -1;
        if constexpr (std::is_move_assignable_v<T>)
            index = buffer_arr->emplace_back(APEX_TypeDefault<T>::value());
        else
        {
            SYS_STATIC_ASSERT_MSG(
                    !detail::APEX_TypeDefaultIsSpecialized_v<T>,
                    "A move constructor must be declared on a type with an explicit APEX default "
                    "value.");
            index = buffer_arr->emplace_back();
        }
        return index;
    }

    void deallocate(void *mem) const override
    {
        UT_Array<T> *buffer_arr = reinterpret_cast<UT_Array<T> *>(mem);
        delete buffer_arr;
    }

    void *getPtrAtIndex(void *mem, exint index) const override
    {
        UT_Array<T> &buffer_arr = *reinterpret_cast<UT_Array<T> *>(mem);
        return &buffer_arr[index];
    }

    void setData(SYS_MAYBE_UNUSED void *mem, SYS_MAYBE_UNUSED const void *val) const override
    {
        if constexpr (std::is_copy_assignable_v<T>)
        {
            const T *typed_val = reinterpret_cast<const T *>(val);
            T *buffer_value = reinterpret_cast<T *>(mem);
            *buffer_value = *typed_val;
        }
        else
            UTdebugPrint("cannot copy assign", myTypeName);
    }

    bool compile(APEX_Buffer *buffer, APEX_Graph *graph, APEX_PortID port) const override
    {
        return APEX_TypeTraits<T>::compile(buffer, graph, port);
    }

    std::type_index typeIndex() const override { return myTypeIndex; }
    bool isCopyable() const override { return std::is_copy_assignable_v<T>; }

    bool isArray() const override { return APEX_IsArrayType<T>::value; }
    bool isVariadic() const override { return APEX_IsVariadicType<T>::value; }
    bool isHandle() const override { return APEX_TypeTraits<T>::isHandle(); }

    const APEX_TypeDefinitionBase *subTypeDef() const override { return mySubTypeDef; }

private:
    const UT_StringLit myTypeName;
    const APEX_TypeDefinitionBase *mySubTypeDef;
    std::type_index myTypeIndex;
};

template <>
class APEX_TypeDefinition<void> : public APEX_VoidTypeDefinition
{
};

/// Return the type definition for a compile-time known type. APEX equivalent of @c typeid().
template <typename T>
static const APEX_TypeDefinitionBase *
findTypeDef()
{
    auto key = typeid(T).name();
    auto it = APEXtypeDefinitions().find(key);
    if (!it.atEnd())
        return it->second;
    // UTdebugPrint("findTypeDef could not find:", key);
    return nullptr;
}

/// Lookup a type definition by its @c repr().
static const APEX_TypeDefinitionBase *
findTypeDef(const UT_StringRef &type_name)
{
    for (auto it = APEXtypeDefinitions().begin(); !it.atEnd(); ++it)
    {
        if (it->second->repr() == type_name)
            return it->second;
    }
    return nullptr;
}

/// Return the @c repr() name for a compile-time known type.
template <typename T>
static const UT_StringRef &
findTypeName()
{
    auto key = typeid(T).name();
    auto it = APEXtypeDefinitions().find(key);
    if (!it.atEnd())
        return it->second->repr();
    return theUndefTypeName.asRef();
}

static bool
isVariadicType(const APEX_TypeDefinitionBase *type)
{
    return type && type->isVariadic();
}

// Check if copyArgData will attempt to perform a copy, or whether it will fail
// due to type issues.
static bool
canCopyArgData(
        const APEX_TypeDefinitionBase *dst,
        const APEX_TypeDefinitionBase *src,
        bool allow_implicit_conversion = false)
{
    if (dst != src)
    {
        if (!allow_implicit_conversion)
            return false;
        if (dst == findTypeDef<Bool>() && src == findTypeDef<Int>())
            return true;
        if (src == findTypeDef<Bool>() && dst == findTypeDef<Int>())
            return true;
        return false;
    }
    return dst->isCopyable();
}

#define APEX_DEF_TYPE_NAME(t) static APEX_TypeDefinition<t> t_dfn_##t{ #t };
#define APEX_DEF_TYPE_NAME_N(t, n) static APEX_TypeDefinition<t> t_dfn_##n{ #t };
#define APEX_DEF_TYPE_RUNDATA(c) \
            inline static APEX_TypeDefinition<RunData> t_dfn_##c{ #c"::RunData" };

/// Defines the type, its array, and variadic arg variants at the same time
#define APEX_DEF_TYPE_NAME_BASIC(type) \
            APEX_DEF_TYPE_NAME(type) \
            APEX_DEF_TYPE_NAME_N(VariadicArg<type>, VariadicArg_##type) \
            /**/
#define APEX_DEF_TYPE_NAME_FULL(type) \
            APEX_DEF_TYPE_NAME_BASIC(type) \
            APEX_DEF_TYPE_NAME(type##Array) \
            APEX_DEF_TYPE_NAME_N(VariadicArg<type##Array>, VariadicArg_##type##Array) \
            /**/

APEX_API extern APEX_VoidTypeDefinition void_type_defn;

} // namespace apex

#endif // end header guard