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 "APEXA_SceneUtils.h"

#include <APEX/APEX_COW.h>
#include <APEX/APEX_ParmDict.h>
#include <GU/GU_OnionSkin.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_StringRef &pattern = "*",
               bool copies_geo=false);

        void clearCachedResult();

        exint getNumOnionSkins(
                const GU_CommonOnionSkinOptions &onion_skin_opts) const
        {
            if (!myOnionSkinOptions)
                return 0;
            return myOnionSkinOptions->getNumOnionSkins(onion_skin_opts);
        }

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

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

        UT_Optional<GU_OnionSkinOptions> myOnionSkinOptions;

        bool myCopiesGeoFlag = false;
    };

    APEXA_SceneInvoke(bool reuse_cached_scene=false);
    ~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.
    /// @param track_output If enabled, the output will be tracked and can be evaluated
    /// in parallel.
    exint addOutput(const UT_StringHolder &path,
                    const UT_Optional<UT_StringHolder> &key,
                    bool copies_geo = false,
                    bool track_output = false);

    /// Adds the default output shapes for each character to the list of outputs that can be evaluated.
    /// @param track_outputs If true, all character shape outputs will be tracked and can be
    /// evaluated in parallel.
    void addCharacterShapeOutputs(bool track_outputs=false);

    /// 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.
    /// @param evaluate_tracked_outputs If true, the tracked outputs will be
    /// evaluated in parallel.
    void updateEvaluationTime(
            apex::Float frame,
            bool evaluate_tracked_ouputs = true);

    /// 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);

    /// Sets the animation cache mode
    void setAnimationCachingMode(APEXA_AnimationCachingMode mode);

    /// Returns the animation caching mode
    APEXA_AnimationCachingMode animationCachingMode() const { return myAnimationCachingMode; }

    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;

private:
    /// The APEX Scene object
    UT_SharedPtr<APEXA_Scene> myScene;

    /// Whether to attempt to reuse a scene in the animation cache
    bool myReuseCachedScene; 

    int64 myDetailId = -1;
    int64 myMetaCacheCount = -1;

    /// Invisible characters from the selection sets.
    UT_StringSet myInvisibleChars;
    APEXA_AnimationCachingMode myAnimationCachingMode = APEXA_AnimationCachingMode::None;

    UT_Array<Output> myOutputs;
};

#endif