HUSD_ShaderTranslator.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 __HUSD_ShaderTranslator_h__
#define __HUSD_ShaderTranslator_h__

#include "HUSD_API.h"

#include <VOP/VOP_Types.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_ThreadSpecificValue.h>
#include <UT/UT_IntArray.h>

#include <utility>

class HUSD_AutoWriteLock;
class HUSD_TimeCode;
class OP_Node;


/// Creates a USD shader primitives from Houdini's nodes.
class HUSD_API HUSD_ShaderTranslator
{
public:
    /// Standard virtual destructor for this abstract base class.
    virtual     ~HUSD_ShaderTranslator() = default;


    /// Returns true if the translator can encode a shader that reports
    /// a given render mask (ie, is a shader for a given render target).
    virtual bool matchesRenderMask( const UT_StringRef &render_mask ) = 0;

    /// @{ Methods that delineate the authoring of a USD material primitive.
    /// The first method is called before this translator is asked to translate
    /// any shader into the given material, while the second one is called after
    /// all relevant shader have been translated.
    /// This allows the translator to do some preparatory or cleanup work.
    /// For example to configure the USD material, or to reset any caches.
    virtual void beginMaterialTranslation( HUSD_AutoWriteLock &lock,
                        const UT_StringRef &usd_material_path );
    virtual void endMaterialTranslation(HUSD_AutoWriteLock &lock,
                        const UT_StringRef &usd_material_path );
    /// @}

    /// Class used for marking the scope as containing an active shader
    /// translator. This allows checking if any shader translator is actively
    /// translating shader nodes to USD at the moment.
    class HUSD_API ActiveToken
    {
    public:
                         ActiveToken();
                        ~ActiveToken();

        /// Returns true if there are any existing token objects 
        /// live in the given thread.
        static bool      hasActiveToken(int thread);

    private:
        static UT_ThreadSpecificValue<int> theActiveTranslatorCount;
    };

    /// Returns true if there are any shader translators executing
    /// on the given thread (ie, if passed current thread's ID, ie
    /// it checks the call originates from a translator on the call stack).
    static bool         isTranslatorActive(int thread)
                            { return ActiveToken::hasActiveToken(thread); }

    /// Defines a USD shader primitive that is part of the USD material.
    /// Ie, the translator will connect the shader to the material output.
    ///
    /// @p usd_material_path - path to the material primitive in which 
    ///         the shader primitive should be created.
    /// @p time_code - time code at which to evaluate any properties
    /// @p shader_node - the Houdini node that represents a shader and that 
    ///         needs to be translated into a USD shader primitive
    /// @p shader_type - some VOPs contains several shaders (eg material
    ///         builders). So this parameters specifies the type of the shader 
    ///         to pick and translate.
    /// @p output_name - the output name of the VOP node that represents
    ///         the shader to pick and translate. It can be an empty string,
    ///         if the VOP node does not have shader outputs.
    virtual void createMaterialShader( HUSD_AutoWriteLock &lock,
                        const UT_StringRef &usd_material_path,
                        const HUSD_TimeCode &time_code,
                        OP_Node &shader_node, 
                        VOP_Type shader_type,
                        const UT_StringRef &output_name) = 0;

    /// Defines a USD shader primitive that is part of a shader network chain.
    /// Ie, the translator will create a shader primitive output, that the 
    /// caller can use to connect as an input to another shader.
    /// 
    /// @p usd_material_path - path to the material primitive in which 
    ///         the shader primitive should be created.
    /// @p usd_parent_path - path to the primitive inside which 
    ///         the shader primitive should be created directly.
    /// @p usd_shader_name - name of the shader primitive to create,
    ///         (may be an empty string, in which case use node name, etc).
    /// @p time_code - time code at which to evaluate any properties
    /// @p shader_node - the Houdini node that represents a shader and that 
    ///         needs to be translated into a USD shader primitive
    /// @p output_name - the output name of the VOP node that needs to be
    ///         translated into USD shader output. This is the output
    ///         the caller is interested in having representation in USD.
    ///
    /// @return The path to the USD shader output attribute corresponding
    ///         to the @p output_name connector on the @p shader_node.
    virtual UT_StringHolder createShader( HUSD_AutoWriteLock &lock,
                        const UT_StringRef &usd_material_path,
                        const UT_StringRef &usd_parent_path,
                        const UT_StringRef &usd_shader_name,
                        const HUSD_TimeCode &time_code,
                        OP_Node &shader_node, 
                        const UT_StringRef &output_name) = 0;


    /// Re-translates the shader parameters given the shader VOP node (and its 
    /// new parameter values).
    /// @p usd_shader_path - the path to the USD shader primitive whose
    ///         input attributes need updating due to node parm value change.
    /// @p time_code - time code at which to evaluate any properties
    /// @p shader_node - Houdini node that represents a shader that 
    ///         needs to be re-translated into the given USD shader primitive.
    /// @p parameter_names - the list  of parameters that have changed.
    ///         If the list is empty, then any of the node's parameters may
    ///         have changed. If it's not empty, then only listed parameters
    ///         have changed.
    virtual void updateShaderParameters( HUSD_AutoWriteLock &lock,
                        const UT_StringRef &usd_shader_path,
                        const HUSD_TimeCode &time_code,
                        OP_Node &shader_node,
                        const UT_StringArray &parameter_names) = 0;

    /// Returns the name of the renderer (render context name) that
    /// should be used in the material output name for that USD shader.
    virtual UT_StringHolder getRenderContextName( OP_Node &shader_node, 
                        const UT_StringRef &output_name) = 0;


    /// Some translators may want to know their ID in the registry.
    virtual void        setID( int id ) { myID = id; }
    virtual int         getID() const   { return myID; }

    /// Designates the nodes as shader node dependents, given their IDs.
    void                setDependentNodeIDs( const UT_IntArray &node_ids )
                        { myDependentNodeIDs = node_ids; }
    const UT_IntArray & getDependentNodeIDs() const
                        { return myDependentNodeIDs; }

private:
    /// Translator's ID.
    int                 myID = -1;

    /// Houdini nodes (LOPs) that depend on translated shader nodes (VOPs).
    UT_IntArray         myDependentNodeIDs;
};

// ============================================================================ 
/// Creates a standard USD Preview Surface shader from Houdini's node.
class HUSD_API HUSD_PreviewShaderTranslator
{
public:
    /// Standard virtual destructor for this abstract base class.
    virtual     ~HUSD_PreviewShaderTranslator() = default;


    /// Returns true if the translator can create a USD Preview Surface shader
    /// for a shader node that reports the given render mask.
    virtual bool matchesRenderContext( const UT_StringRef &render_context ) = 0;


    /// Creates a USD Preview Surface shader primitive for the USD material.
    ///
    /// @p usd_material_path - path to the material primitive in which 
    ///         the preview shader primitive should be created.
    /// @p usd_shader_path - path to a specific render context shader primitive
    ///         based on which the universal render context preview shader 
    ///         should be created.
    /// @p time_code - time code at which to evaluate and author any properties.
    virtual void createMaterialPreviewShader( HUSD_AutoWriteLock &lock,
                        const UT_StringRef &usd_material_path,
                        const UT_StringRef &usd_shader_path,
                        const HUSD_TimeCode &time_code ) = 0;


    /// Destroys the USD Preview Surface shader and its input chains.
    virtual void deleteMaterialPreviewShader( HUSD_AutoWriteLock &lock,
                        const UT_StringRef &usd_material_path ) = 0;

    /// Re-translates the shader parameters given the shader VOP node (and its 
    /// new parameter values).
    /// @p usd_shader_path - the path to the USD main surface shader primitive, 
    ///         based on which the preview shader nput attributes need to be 
    ///         updated, due to node parm value change.
    /// @p time_code - time code at which to evaluate and author any properties.
    virtual void updateMaterialPreviewShaderParameters(HUSD_AutoWriteLock &lock,
                        const UT_StringRef &usd_main_shader_path,
                        const HUSD_TimeCode &time_code ) = 0;
};

// ============================================================================ 
/// Keeps a list of known translators that define a USD shader prim from 
/// Houdini shader nodes.
class HUSD_API HUSD_ShaderTranslatorRegistry
{
public:
    /// Returns a singelton instance.
    static HUSD_ShaderTranslatorRegistry &get();


    /// Adds the translator to the list of known translators.
    void        registerShaderTranslator( HUSD_ShaderTranslator &translator );

    /// Removes the translator from the list of known translators.
    void        unregisterShaderTranslator( HUSD_ShaderTranslator &translator );

    /// Returns a translator that accepts the given render target mask.
    /// If no translator is found, returns nullptr.
    HUSD_ShaderTranslator * findShaderTranslator( const OP_Node &node ) const;

    /// Returns the internal ID number of a translator that handles the
    /// translation of the given node.
    int         findShaderTranslatorID( const OP_Node &node ) const;


    /// Adds the translator to the list of known translators.
    void    registerPreviewShaderTranslator( HUSD_PreviewShaderTranslator &t );

    /// Removes the translator from the list of known translators.
    void    unregisterPreviewShaderTranslator( HUSD_PreviewShaderTranslator &t);

    /// Returns a translator that accepts the given USD render context name.
    HUSD_PreviewShaderTranslator * findPreviewShaderTranslator(
                        const UT_StringRef &usd_render_context_name ) const;

    /// Removes all translators from the registry.
    /// Should only be called on shutdown of the process.
    void        clear();

    /// Informs the registry about a new translation of node into a USD prim.
    void        reportShaderTranslation( const OP_Node &node, 
                        const UT_StringRef &usd_shader_path );

    /// @{ Adds and removes a node from the translation observers list.
    /// Observers are basicaly interested in creation of any new USD shader
    /// primitive and the original VOP node based on which it was created.
    /// Translators report such creation events with reportShaderTranslation(),
    /// and observer LOPs can use that info to selectively re-translate
    /// single USD prim when a only single VOP changed.
    using TranslationRecord  = std::pair<int, UT_StringHolder>;
    using TranslationRecords = UT_Array<TranslationRecord>;
    void                    addTranslationObserver( const OP_Node &node );
    TranslationRecords      removeTranslationObserver( const OP_Node &node );
    /// @}


private:
    /// List of known shader translators.
    UT_Array<HUSD_ShaderTranslator *>       myTranslators;

    /// List of known preview shader translators.
    UT_Array<HUSD_PreviewShaderTranslator *> myPreviewTranslators;

    /// @{ IDs of translation observer nodes and translations reported for them.
    UT_Array<int>                           myTranslationObservers;
    UT_Array<TranslationRecords>            myTranslations;
    /// @}
};

#endif