GU_AgentBlendShapeUtils.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.
*/

#ifndef __GU_AgentBlendShapeUtils__
#define __GU_AgentBlendShapeUtils__

#include "GU_API.h"

#include "GU_DetailHandle.h"
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_Span.h>

class GU_AgentRig;
class GU_AgentShapeLib;

namespace GU_AgentBlendShapeUtils
{
/// Adds in-between shapes to a blendshape input (the primary shape).
/// This sets up the required detail attributes ("blendshape_shapenames" and
/// "blendshape_inbetweenweights") on the primary shape's geometry.
/// The shapes should be separately added to the shape library.
void GU_API addInBetweenShapes(GU_Detail &primary_shape_gdp,
                               const UT_StringArray &inbetween_shape_names,
                               const UT_Array<fpreal> &inbetween_weights);

/// Adds blendshape inputs to a shape.
/// This sets up the required detail attributes ("blendshape_shapenames" and
/// "blendshape_channels") on the base shape's geometry.
/// The shapes should be separately added to the shape library.
void GU_API addInputsToBaseShape(GU_Detail &base_shape,
                                 const UT_StringArray &shape_names,
                                 const UT_StringArray &channel_names);

/// Adds detail attributes to the base shape ("blendshape_ptidattr",
/// "blendshape_primidattr") for the blendshape deformer's optional parameters.
void GU_API setDeformerParameters(GU_Detail &base_shape,
                                  const UT_StringHolder &attribs,
                                  const UT_StringHolder &ptidattr,
                                  const UT_StringHolder &primidattr);

/// Reads the detail attributes for the blendshape deformer's optional
/// parameters.
/// If not specified, attribs is set to "P", ptidattr is set to "id", and
/// primidattr is set to "".
void GU_API getDeformerParameters(const GU_Detail &base_shape,
                                  UT_StringHolder &attribs,
                                  UT_StringHolder &ptidattr,
                                  UT_StringHolder &primidattr);

/// Removes the detail attributes added by addInputsToBaseShape() and
/// setDeformerParameters().
void GU_API clearInputShapes(GU_Detail &base_shape);

/// Removes the detail attributes added by addInBetweenShapes().
void GU_API clearInBetweenShapes(GU_Detail &base_shape);

using FloatType = fpreal32;
using FloatArray = UT_Array<FloatType>;

class GU_API InputCache
{
public:
    /// Populates the cache. If the optional rig is not provided,
    /// inputChannelIndex() will be invalid.
    bool reset(
            const GU_Detail &base_shape,
            const GU_AgentShapeLib &shapelib,
            const GU_AgentRig *rig,
            UT_StringHolder *warnings = nullptr);

    /// Returns the number of blendshape inputs (primary shapes).
    exint numInputs() const { return myChannelIndices.entries(); }

    /// Returns the GU_AgentRig channel index for the specified input.
    exint inputChannelIndex(exint i) const
    {
        return myChannelIndices[i];
    }

    /// Returns the name of the primary target shape for the specified input.
    const UT_StringHolder &primaryShapeName(exint i) const;

    /// Returns the names and weights of the in-between target shapes for the
    /// specified input (i.e. shapes with weight 0 or 1 are skipped).
    void getInBetweenShapes(exint i, UT_StringArray &shape_names,
                            FloatArray &shape_weights) const;

    /// Appends to the provided list of shapes and weights, given an input
    /// index and weight value. When there are in-between shapes this selects
    /// the appropriate pair of shapes to blend between based on the provided
    /// weight.
    void getShapes(exint i, FloatType w, UT_Array<const GU_Detail *> &shapes,
                   FloatArray &weights) const;

    /// The total number of primary and in-between shapes.
    exint numTargetShapes() const { return myNumTargets; }

    /// Returns a list of the geometry for the target shapes.
    UT_Array<GU_ConstDetailHandle> targetShapes() const;

    /// Fill a buffer (of max length numTargetShapes()) with the index and
    /// weight for each active target shape based on the provided rig channel
    /// values. Returns the number of active target shapes.
    int fillTargetShapeWeightsFromChannels(
            const UT_Span<const FloatType> &rig_channel_values,
            std::pair<int32, fpreal32> *target_weights) const;

    /// Variant of fillTargetShapeWeightsFromRig() which instead expects the
    /// weight value for each blendshape input, rather than the rig's channel
    /// values (i.e. the span's length should be numInputs(), and contain the
    /// values for inputChannelIndex(i))
    int fillTargetShapeWeightsFromInputWeights(
            const UT_Span<const FloatType> &input_weights,
            std::pair<int32, fpreal32> *target_weights) const;

private:
    /// Returns the number of shapes for the specified input. If there are
    /// in-between shapes this is >= 3, since there are implicit shapes with
    /// weights 0 and 1, and otherwise 1 is returned.
    inline exint numShapes(exint i) const
    {
        return myInputStarts[i + 1] - myInputStarts[i];
    }

    void
    addInput(exint channel_idx, const UT_Array<GU_ConstDetailHandle> &shapes,
             const UT_StringArray &shape_names,
             const FloatArray &shape_weights);

    /// Channel indices for GU_AgentRig.
    UT_Array<exint> myChannelIndices;

    /// Index into myShapes, myShapeWeights, and myShapeNames for where the
    /// shapes for each channel start.
    /// The shapes for each input are ordered by weight.
    UT_Array<exint> myInputStarts;

    UT_Array<GU_ConstDetailHandle> myShapes;
    FloatArray myShapeWeights;
    UT_StringArray myShapeNames;

    /// Index between [0, myNumTargets) for the primary / in-between shapes.
    /// The implicit null shapes have a value of -1.
    UT_Array<exint> myTargetIds;
    exint myNumTargets = 0;
};

} // namespace GU_AgentBlendShapeUtils

#endif