// Copyright (c) 2022-2023, NVIDIA CORPORATION. All rights reserved.
//
// NVIDIA CORPORATION and its licensors retain all intellectual property
// and proprietary rights in and to this software, related documentation
// and any modifications thereto. Any use, reproduction, disclosure or
// distribution of this software and related documentation without an express
// license agreement from NVIDIA CORPORATION is strictly prohibited.
//

//! @file IPopulatePass.h
//!
//! @brief Defines @ref omni::graph::exec::unstable::IPopulatePass.
#pragma once

#include <omni/graph/exec/unstable/IPass.h>

namespace omni
{
namespace graph
{
namespace exec
{
namespace unstable
{

// forward declarations needed by interface declaration
class IGraphBuilder;
class INode;
class IPopulatePass;
class IPopulatePass_abi;

//! Base class for populate passes.
//!
//! Register a populate pass with @ref OMNI_GRAPH_EXEC_REGISTER_POPULATE_PASS().  When registering a pass, a "name to
//! match" is also specified.  This name is the name of a node or definition on which the registered pass should
//! populate.
//!
//! Populate passes are typically the first pass type to run in the pass pipeline. When a node is encountered during
//! construction, only a single populate pass will get a chance to populate the newly discovered node. If no pass is
//! registered against the node's name, the node definition's name is used to find a population pass to run.
//!
//! Populate pass is allowed to attach a new definition to a node it runs on.
//!
//! Minimal rebuild of the execution graph topology should be considered by the pass each time it runs. Pass pipeline
//! leaves the responsibility of deciding if pass needs to run to the implementation. At minimum it can rely on
//! verifying that topology of @ref omni::graph::exec::unstable::NodeGraphDef it generated before is still valid or
//! @ref omni::graph::exec::unstable::NodeDef has not changed.
//!
//! See @ref  groupOmniGraphExecPasses for more pass related functionality.
class IPopulatePass_abi : public omni::core::Inherits<IPass, OMNI_TYPE_ID("omni.graph.exec.unstable.IPopulatePass")>
{
protected:
    //! Call from pass pipeline to apply graph transformations on a given node (definition or topology).
    virtual OMNI_ATTR("throw_result") omni::core::Result run_abi(IGraphBuilder* builder, INode* node) noexcept = 0;
};

//! Smart pointer managing an instance of @ref IPopulatePass.
using PopulatePassPtr = omni::core::ObjectPtr<IPopulatePass>;

} // namespace unstable
} // namespace exec
} // namespace graph
} // namespace omni

// generated API declaration
#define OMNI_BIND_INCLUDE_INTERFACE_DECL
#include <omni/graph/exec/unstable/IPopulatePass.gen.h>

//! @copydoc omni::graph::exec::unstable::IPopulatePass_abi
//!
//! @ingroup  groupOmniGraphExecPasses groupOmniGraphExecInterfaces
class omni::graph::exec::unstable::IPopulatePass
    : public omni::core::Generated<omni::graph::exec::unstable::IPopulatePass_abi>
{
};

// additional headers needed for API implementation
#include <omni/graph/exec/unstable/IGraphBuilder.h>
#include <omni/graph/exec/unstable/INode.h>

// generated API implementation
#define OMNI_BIND_INCLUDE_INTERFACE_IMPL
#include <omni/graph/exec/unstable/IPopulatePass.gen.h>
