APEXA_SceneInvoke.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 __APEXA_SCENE_INVOKE_H__
#define __APEXA_SCENE_INVOKE_H__

#include "APEXA_API.h"

#include <APEX/APEX_COW.h>
#include <APEX/APEX_ParmDict.h>
#include <UT/UT_Optional.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringSet.h>
#include <SYS/SYS_Types.h>

class APEXA_Scene;
class GU_Detail;

class APEXA_API APEXA_SceneInvoke
{
public:
    struct APEXA_API Output
    {
        Output() = default;
        Output(const UT_StringHolder &path,
               const UT_Optional<UT_StringHolder> &key,
               const UT_Optional<UT_StringHolder> &pattern = UT_NULLOPT,
               bool copies_geo=false);

        void clearCachedResult();

        UT_StringHolder myPath;
        UT_Optional<UT_StringHolder> myKey;
        UT_Optional<UT_StringHolder> myPattern;

        UT_Optional<apex::ApexGeometry> myGeometry;
        UT_Optional<apex::Dict> myDict;

        bool myCopiesGeoFlag = false;
    };

    APEXA_SceneInvoke();
    ~APEXA_SceneInvoke();

    UT_NON_COPYABLE(APEXA_SceneInvoke);

    /// Update the source geometry for the scene.
    /// Returns true if the scene was reloaded. The outputs are also cleared if the scene changed.
    bool updateSourceGeometry(
            const GU_Detail &detail,
            UT_StringHolder &error,
            bool preload_animation_clips=false);

    /// Clear the outputs.
    void clearOutputs();

    /// Returns the registered outputs, with their evaluated results if evaluateOutput() has been called.
    const UT_Array<Output> &getOutputs() const { return myOutputs; }

    /// Registers a specific output for evaluation, and returns its index into getOutputs().
    /// @param copies_geo If enabled, a replaceWith call will be run the copies any
    /// geometries out of the scene instead of grabbing the detail handle. This can
    /// improve the efficiency of the APEX graph when the output geometry receives preserve
    /// requests.
    exint addOutput(const UT_StringHolder &path,
                    const UT_Optional<UT_StringHolder> &key,
                    bool copies_geo = false);

    /// Adds the default output shapes for each character to the list of outputs that can be evaluated.
    void addCharacterShapeOutputs();

    /// Returns the default output shapes for each character. This can be used instead of
    /// addCharacterShapeOutputs() if additional processing / validation is needed before
    /// registering outputs.
    /// @param include_invisible_chars If enabled, includes characters which are currently hidden in
    /// the selection sets.
    UT_Array<Output> findCharacterShapeOutputs(
        bool include_invisible_chars = false) const;

    /// Returns the named geometry outputs for each character.
    /// @param output_name
    /// @param include_invisible_chars If enabled, includes characters which
    /// are currently hidden in the selection sets.
    UT_Array<Output> findCharacterGeometryOutputs(
        const UT_StringHolder &output_name,
        bool include_invisible_chars = false) const;

    /// Returns a list of the available output paths in the scene,
    /// e.g. /electra.char/Base.rig/output
    UT_StringArray findOutputPaths() const;

    /// Analyzes the graph to determine if the output shape is only deformed by a bonedeform SOP.
    /// If successful, returns the paths which should be evaluated to obtain the rest geometry, rest
    /// skeleton, and animated skeleton.
    /// This assumes that the rest_shape and rest_skel are connected directly to an input from the bonedeform.
    bool findSkinningInputsForShape(
            const Output &deform_shape_output,
            Output &rest_shape_output,
            Output &rest_skel_output,
            Output &anim_skel_output) const;

    /// Analyzes the graph to determine if the output shape is only deformed by a bonedeform SOP.
    /// If successful, returns the path for the animated skeleton.
    /// This can succeed even when the rest_skel and rest_shape aren't connected directly to an input from the bonedeform.
    bool findAnimSkelInputForShape(
            const Output &deform_shape_output,
            Output &anim_skel_output) const;

    /// Update the scene to the specified time, clearing any cached output results.
    void updateEvaluationTime(apex::Float frame);

    /// Evaluate the specified output at the scene's current time. Returns false if any errors occurred.
    bool evaluateOutput(exint output_idx, UT_StringHolder &error);

    /// Set the active animation clip.
    /// @param clip_path Path to the clip to activate or empty string to use
    ///  the default one from the scene..
    /// @param error Outputs any error messages if the active clip could not be set.
    /// @return true if successful, false otherwise
    bool setActiveClip(const UT_StringHolder &clip_path, UT_StringHolder &error);

    /// Returns the resolved active clip path on the scene.
    UT_StringHolder getActiveClipPath() const;

    /// Returns a list of the available clips in the scene.
    UT_StringArray getClipPaths() const;

    /// Override a character geometry input with a new geometry.
    ///  This can be used to inject external animated geometries.
    ///  Call updateEvaluationTime() to force a refresh().
    bool setCharacterGeoInput(
        const UT_StringHolder &character_path,
        const UT_StringHolder &geo_name,
        const GU_ConstDetailHandle &geo);

    APEXA_Scene *getScene() { return myScene.get(); }

    /// Returns whether the name of a packed primitive is likely an item in a packed character
    /// scene, e.g. "*.char"
    /// This can be used to identify geometry that should be interpreted as a character scene.
    static bool isCharacterSceneItemName(const UT_StringRef &name);

    /// Returns whether there are any channel primitives in the scene. This can be used to only load
    /// / evaluate the scene when animation is present.
    static bool hasAnimation(const GU_ConstDetailHandle &scene_gdh);

private:
    /// Load visibility information from selection sets.
    void loadSelectionSetVisibility(const GU_Detail &detail);
    /// Returns whether the rig is associated with a visible character.
    bool isRigVisible(const UT_StringView &rig_path) const;

    UT_UniquePtr<APEXA_Scene> myScene;
    int64 myDetailId = -1;
    int64 myMetaCacheCount = -1;

    /// Invisible characters from the selection sets.
    UT_StringSet myInvisibleChars;

    UT_Array<Output> myOutputs;
};

#endif