XUSD_AutoCollection.h

Go to the documentation of this file.

/*
 * Copyright 2019 Side Effects Software Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */

#ifndef __XUSD_AutoCollection_h__
#define __XUSD_AutoCollection_h__

#include "HUSD_API.h"
#include "HUSD_TimeCode.h"
#include "HUSD_Utils.h"
#include "XUSD_PathSet.h"
#include <UT/UT_Array.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>
#include <pxr/usd/sdf/path.h>
#include <pxr/usd/usd/stage.h>

extern "C" {
    SYS_VISIBILITY_EXPORT extern void   newAutoCollection(void *unused);
};
class HUSD_AutoAnyLock;

PXR_NAMESPACE_OPEN_SCOPE

class XUSD_AutoCollection;

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

    virtual bool         canCreateAutoCollection(const char *token) const = 0;
    virtual XUSD_AutoCollection *create(
            const UT_StringHolder &collectionname,
            const UT_StringArray &orderedargs,
            const UT_StringMap<UT_StringHolder> &namedargs,
            HUSD_AutoAnyLock &lock,
            HUSD_PrimTraversalDemands demands,
            int nodeid,
            const HUSD_TimeCode &timecode) const = 0;
};

template <class AutoCollection>
class XUSD_SimpleAutoCollectionFactory : public XUSD_AutoCollectionFactory
{
public:
                         XUSD_SimpleAutoCollectionFactory(const char *cname)
                             : myCollectionName(cname)
                         { }
                        ~XUSD_SimpleAutoCollectionFactory() override
                         { }

    bool                 canCreateAutoCollection(
                                const char *cname) const override
    {
        return (myCollectionName == cname);
    }
    XUSD_AutoCollection *create(
            const UT_StringHolder &collectionname,
            const UT_StringArray &orderedargs,
            const UT_StringMap<UT_StringHolder> &namedargs,
            HUSD_AutoAnyLock &lock,
            HUSD_PrimTraversalDemands demands,
            int nodeid,
            const HUSD_TimeCode &timecode) const override
    {
        if (collectionname == myCollectionName)
            return new AutoCollection(collectionname, orderedargs, namedargs,
                lock, demands, nodeid, timecode);

        return nullptr;
    }

private:
    UT_StringHolder      myCollectionName;
};

class HUSD_API XUSD_AutoCollection
{
public:
                         XUSD_AutoCollection(
                                const UT_StringHolder &collectionname,
                                const UT_StringArray &orderedargs,
                                const UT_StringMap<UT_StringHolder> &namedargs,
                                HUSD_AutoAnyLock &lock,
                                HUSD_PrimTraversalDemands demands,
                                int nodeid,
                                const HUSD_TimeCode &timecode);
    virtual             ~XUSD_AutoCollection();

    // Determines whether or not this class works in random access mode.
    virtual bool         randomAccess() const = 0;

    // INSTANCE ID CONTRACT (applies to every `instance_ids` output below):
    // When a point instancer is matched per-instance, the id array stored for
    // that instancer MUST be sorted in ascending order and contain no
    // duplicates. The pattern matching layer relies on this invariant: it is
    // carried unchanged into the XUSD_InstanceMatchData payload, and
    // XUSD_PathPattern::combineMatchData performs union/intersection/difference
    // as a linear merge of two sorted, duplicate-free arrays. Implementations
    // that gather ids in instancer (authored) order must sort and de-duplicate
    // before returning, e.g. with UT_Array::sortAndRemoveDuplicates(); the
    // shared matchPointInstances() helper already does this.

    // A non-random access auto collection does its own traversal of the stage
    // all at once when the auto collection is created, generating a full set
    // of all matching paths at once. See the INSTANCE ID CONTRACT above for the
    // ordering requirement on `instance_ids`.
    virtual void         matchPrimitives(XUSD_PathSet &matches,
                                UT_StringMap<UT_Array<int64>> *instance_ids)
                                const
                         { UT_ASSERT(false); }

    // A random access auto collection gets no benefit from being executed
    // as a depth first traversal of the whole stage. It will be called for
    // each primitive as part of the overall pattern matching process. See the
    // INSTANCE ID CONTRACT above for the ordering requirement on `instance_ids`.
    virtual bool         matchRandomAccessPrimitive(const SdfPath &path,
                                bool *prune_branch,
                                UT_Array<int64> *instance_ids = nullptr) const
                         { UT_ASSERT(false); return false; }

    virtual bool         getMayBeTimeVarying() const
                         { return myMayBeTimeVaryingSubPattern; }

    const UT_StringHolder &getTokenParsingError() const
                         { return myTokenParsingError; }

    // Static functions for common argument parsing tasks.
    static bool          parseBool(const UT_StringRef &str);
    static bool          parseInt(const UT_StringRef &str,
                                exint &i);
    static bool          parseFloat(const UT_StringRef &str,
                                fpreal64 &flt);
    static bool          parseVector2(const UT_StringRef &str,
                                UT_Vector2D &vec);
    static bool          parseVector3(const UT_StringRef &str,
                                UT_Vector3D &vec);
    static bool          parseVector4(const UT_StringRef &str,
                                UT_Vector4D &vec);
    static bool          parseTimeRange(const UT_StringRef &str,
                                fpreal64 &tstart,
                                fpreal64 &tend,
                                fpreal64 &tstep);

    // Parse a source pattern string.
    // Note that `timevaryingflag` will only ever be *set* (to `true`),
    // (if the pattern is timevarying of course), but never *unset* (to `false`) 
    static bool          parsePattern(const UT_StringRef &str,
                                HUSD_AutoAnyLock &lock,
                                HUSD_PrimTraversalDemands demands,
                                int nodeid,
                                const HUSD_TimeCode &timecode,
                                bool respect_instance_proxy_demands,
                                XUSD_PathSet &paths,
                                bool *timevaryingflag,
                                UT_StringMap<UT_Array<int64>>
                                    *instance_ids = nullptr);
    // Parse a source pattern string, but only return the first result.
    static bool          parsePatternSingleResult(const UT_StringRef &str,
                                HUSD_AutoAnyLock &lock,
                                HUSD_PrimTraversalDemands demands,
                                int nodeid,
                                const HUSD_TimeCode &timecode,
                                bool respect_instance_proxy_demands,
                                SdfPath &path,
                                bool *timevaryingflag);

    static bool          canCreateAutoCollection(const char *token);
    static XUSD_AutoCollection *create(const char *token,
                                HUSD_AutoAnyLock &lock,
                                HUSD_PrimTraversalDemands demands,
                                int nodeid,
                                const HUSD_TimeCode &timecode);
    static void          registerPlugins();
    static void          registerPlugin(XUSD_AutoCollectionFactory *factory);

protected:
    UT_StringArray               myOrderedArgs;
    UT_StringMap<UT_StringHolder>myNamedArgs;
    bool                         myMayBeTimeVaryingSubPattern;
    HUSD_AutoAnyLock            &myLock;
    HUSD_PrimTraversalDemands    myDemands;
    int                          myNodeId;
    UsdTimeCode                  myUsdTimeCode;
    HUSD_TimeCode                myHusdTimeCode;
    UT_StringHolder              myTokenParsingError;

private:
    // Proeprty related plugins were broken out into a separate file just to
    // keep file size under control, but this meant having a separate plugin
    // registration function for collections in XUSD_PropertAutoCollection.C.
    static void registerPropertyPlugins();

    static UT_Array<XUSD_AutoCollectionFactory *> theFactories;
};

class HUSD_API XUSD_SimpleAutoCollection : public XUSD_AutoCollection
{
public:
                         XUSD_SimpleAutoCollection(
                                const UT_StringHolder &collectionname,
                                const UT_StringArray &orderedargs,
                                const UT_StringMap<UT_StringHolder> &namedargs,
                                HUSD_AutoAnyLock &lock,
                                HUSD_PrimTraversalDemands demands,
                                int nodeid,
                                const HUSD_TimeCode &timecode);
                        ~XUSD_SimpleAutoCollection() override;

    bool                 randomAccess() const override
                         { return false; }
    void                 matchPrimitives(XUSD_PathSet &matches,
                                UT_StringMap<UT_Array<int64>> *instance_ids)
                                const override;
    // If this fills `instance_ids` for a point instancer, the ids must be
    // sorted and duplicate-free (see the INSTANCE ID CONTRACT in
    // XUSD_AutoCollection).
    virtual bool         matchPrimitive(const UsdPrim &prim,
                                bool *prune_branch,
                                UT_Array<int64> *instance_ids) const = 0;
};

class HUSD_API XUSD_RandomAccessAutoCollection : public XUSD_AutoCollection
{
public:
                         XUSD_RandomAccessAutoCollection(
                                const UT_StringHolder &collectionname,
                                const UT_StringArray &orderedargs,
                                const UT_StringMap<UT_StringHolder> &namedargs,
                                HUSD_AutoAnyLock &lock,
                                HUSD_PrimTraversalDemands demands,
                                int nodeid,
                                const HUSD_TimeCode &timecode);
                        ~XUSD_RandomAccessAutoCollection() override;

    bool                 randomAccess() const override
                         { return true; }
    bool                 matchRandomAccessPrimitive(const SdfPath &path,
                                bool *prune_branch,
                                UT_Array<int64> *instance_ids = nullptr)
                                const override;
    // If this fills `instance_ids` for a point instancer, the ids must be
    // sorted and duplicate-free (see the INSTANCE ID CONTRACT in
    // XUSD_AutoCollection).
    virtual bool         matchPrimitive(const UsdPrim &prim,
                                bool *prune_branch,
                                UT_Array<int64> *instance_ids) const = 0;
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif