valueTransform.h

//
// Copyright 2025 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
 
#ifndef PXR_BASE_VT_VALUE_TRANSFORM_H
#define PXR_BASE_VT_VALUE_TRANSFORM_H
 
#include "pxr/pxr.h"
 
#include "pxr/base/vt/dictionary.h"
#include "pxr/base/vt/types.h"
#include "pxr/base/vt/value.h"
#include "pxr/base/vt/valueRef.h"
 
#include <optional>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class Vt_TransformImpl
{
private:
    template <class Xf>
    friend bool
    VtValueCanTransform(VtValueRef obj, Xf const &xfObj);
    
    template <class Xf>
    friend VtValue
    VtValueTryTransform(VtValueRef obj, Xf const &xfObj);
 
    VT_API
    static bool
    Can(VtValueRef obj, std::type_info const &xfType);
    
    VT_API
    static VtValue
    Try(VtValueRef x, std::type_info const &xfType, void const *xfObj,
        TfFunctionRef<VtValue (VtValueRef)>);
};
 
template <class Xf>
bool
VtValueCanTransform(VtValueRef obj, Xf const &xfObj)
{
    if (obj.IsEmpty() || !obj.CanTransform()) {
        return false;
    }
    return Vt_TransformImpl::Can(obj, typeid(xfObj));
}
 
template <class Xf>
VtValue
VtValueTryTransform(VtValueRef obj, Xf const &xfObj)
{
    if (obj.IsEmpty() || !obj.CanTransform()) {
        return {};
    }
    // Helper for type-erased transforms.
    auto erasedXf = [&xfObj](VtValueRef in) -> VtValue {
        return VtValueTryTransform(in, xfObj);
    };
    return Vt_TransformImpl
        ::Try(obj, typeid(xfObj),
              static_cast<void const *>(std::addressof(xfObj)), erasedXf);
}
 
// Registration helper.
VT_API void
Vt_RegisterTypedTransform(
    std::type_info const &objType,
    std::type_info const &xfType,
    void (*voidFn)(),
    VtValue (*xform)(VtValueRef, void const *, void (*)()));
 
template <bool RegisterForArrays, class T, class Xf>
void
Vt_RegisterTransformImpl(T (*fn)(T const &obj, Xf const &xform))
{
    static_assert(!VtIsKnownValueType<T>(),
                  "Unexpected transform registration for one of the "
                  "known value types");
 
    static_assert(VtValueTypeCanTransform<T>::value,
                  "Use VT_VALUE_TYPE_CAN_TRANSFORM or directly specialize "
                  "VtValueTypeCanTransform<> before registering transform "
                  "functionality");
 
    using TypedFn = T (*)(T const &, Xf const &);
    using VoidFn = void (*)();
 
    VoidFn voidFn = reinterpret_cast<VoidFn>(fn);
    Vt_RegisterTypedTransform(
        typeid(T), typeid(Xf), voidFn,
        [](VtValueRef obj, void const *xf, void (*vFn)()) {
            TypedFn tFn = reinterpret_cast<TypedFn>(vFn);
            TF_DEV_AXIOM(obj.IsHolding<T>());
            return VtValue {
                tFn(obj.UncheckedGet<T>(), *static_cast<Xf const *>(xf))
            };
        });
 
    // Register array & array edit xforms of the same, if requested.
    if constexpr (RegisterForArrays) {
        // Arrays.
        Vt_RegisterTypedTransform(
            typeid(VtArray<T>), typeid(Xf), voidFn,
            [](VtValueRef obj, void const *xf, void (*vFn)()) {
                TypedFn tFn = reinterpret_cast<TypedFn>(vFn);
                TF_DEV_AXIOM(obj.IsHolding<VtArray<T>>());
                VtArray<T> const &src = obj.UncheckedGet<VtArray<T>>();
                VtArray<T> xformed;
                T const *srcPtr = src.cdata();
                Xf const &xform = *static_cast<Xf const *>(xf);
                xformed.resize(src.size(), [&](T *first, T *last) {
                    while (first != last) {
                        new (first++) T { tFn(*srcPtr++, xform) };
                    }
                });
                return VtValue::Take(xformed);
            });
 
        // Array Edits.
        Vt_RegisterTypedTransform(
            typeid(VtArrayEdit<T>), typeid(Xf), voidFn,
            [](VtValueRef obj, void const *xf, void (*vFn)()) {
                TypedFn tFn = reinterpret_cast<TypedFn>(vFn);
                TF_DEV_AXIOM(obj.IsHolding<VtArrayEdit<T>>());
                VtArrayEdit<T> const &src = obj.UncheckedGet<VtArrayEdit<T>>();
                VtArrayEdit<T> xformed = src;
                Xf const &xform = *static_cast<Xf const *>(xf);
                for (T &elem: xformed.GetMutableLiterals()) {
                    elem = tFn(elem, xform);
                }
                return VtValue::Take(xformed);
            });
    }
}
    
template <class T, class Xf>
void
VtRegisterTransformNoArrays(T (*fn)(T const &obj, Xf const &xform))
{
    Vt_RegisterTransformImpl</*RegisterForArrays=*/false>(fn);
}        
 
template <class T, class Xf>
void
VtRegisterTransform(T (*fn)(T const &obj, Xf const &xform))
{
    Vt_RegisterTransformImpl</*RegisterForArrays=*/true>(fn);
}
 
VT_API void
Vt_RegisterErasedTransform(
    std::type_info const &objType,
    void (*voidFn)(),
    VtValue (*xform)(VtValueRef, void (*)(),
                     TfFunctionRef<VtValue (VtValueRef)>));
 
template <class T>
void
VtRegisterErasedTransform(
    std::optional<T> (*fn)(T const &obj, TfFunctionRef<VtValue (VtValueRef)>))
{
    static_assert(!VtIsKnownValueType<T>(),
                  "Unexpected transform registration for one of the "
                  "known value types");
 
    static_assert(VtValueTypeCanTransform<T>::value,
                  "Use VT_VALUE_TYPE_CAN_TRANSFORM or specialize "
                  "VtValueTypeCanTransform<> before registering transform "
                  "functionality");
 
    using TypedFn = std::optional<T> (*)(
        T const &, TfFunctionRef<VtValue (VtValueRef)>);
    using VoidFn = void (*)();
 
    VoidFn voidFn = reinterpret_cast<VoidFn>(fn);
    Vt_RegisterErasedTransform(
        typeid(T), voidFn,
        [](VtValueRef obj, VoidFn vFn,
           TfFunctionRef<VtValue (VtValueRef)> xform) {
            TypedFn tFn = reinterpret_cast<TypedFn>(vFn);
            TF_DEV_AXIOM(obj.IsHolding<T>());
            std::optional<T> optT = tFn(obj.UncheckedGet<T>(), xform);
            VtValue ret;
            if (optT) {
                ret = std::move(*optT);
            }
            return ret;
        });
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_BASE_VT_VALUE_TRANSFORM_H