Extension: omni.graph.template.cpp-2.20.0

Documentation Generated: Oct 24, 2024

Changelog

Overview

This is the gold standard template for creating a Kit extension that contains only C++ OmniGraph nodes.

The Files

To use this template first copy the entire directory into a location that is visible to your build, such as source/extensions. The copy will have this directory structure. The highlighted lines should be renamed to match your extension, or removed if you do not want to use them.

omni.graph.template.cpp/
    config/
        extension.toml
    data/
        icon.svg
        preview.png
    docs/
        CHANGELOG.md
        directory.txt
        Overview.md
        README.md
    nodes/
        OgnTemplateNodeCpp.cpp
        OgnTemplateNodeCpp.ogn
    plugins/
        Module.cpp
    premake5.lua

The Build File

Kit normally uses premake for building so this example shows how to use the template premake5.lua file to customize your build. By default the build file is set up to correspond to the directory structure shown above. By using this standard layout the utility functions can do most of the work for you.

 1-- --------------------------------------------------------------------------------------------------------------------
 2-- Build file for the build tools used by the OmniGraph C++ extension. These are tools required in order to
 3-- run the build on that extension, and all extensions dependent on it.
 4
 5-- --------------------------------------------------------------------------------------------------------------------
 6-- This sets up a shared extension configuration, used by most Kit extensions.
 7local ext = get_current_extension_info()
 8
 9-- --------------------------------------------------------------------------------------------------------------------
10-- Set up a variable containing standard configuration information for projects containing OGN files
11local ogn = get_ogn_project_information(ext, "omni/graph/template/cpp")
12
13-- --------------------------------------------------------------------------------------------------------------------
14-- Put this project into the "omnigraph" IDE group
15ext.group = "omnigraph"
16
17-- --------------------------------------------------------------------------------------------------------------------
18-- Set up the basic shared project information first
19project_ext( ext )
20
21-- --------------------------------------------------------------------------------------------------------------------
22-- Define a build project to process the ogn files to create the generated code that will be used by the node
23-- implementations. The (optional) "toc" value points to the directory where the table of contents with the OmniGraph
24-- nodes in this extension will be generated. Omit it if you will be generating your own table of contents.
25project_ext_ogn( ext, ogn, { toc="docs/Overview.md" } )
26
27-- --------------------------------------------------------------------------------------------------------------------
28-- The main plugin project is what implements the nodes and extension interface
29project_ext_plugin( ext, ogn.plugin_project )
30    -- These lines add the files in the project to the IDE where the first argument is the group and the second
31    -- is the set of files in the source tree that are populated into that group.
32    add_files("impl", ogn.plugin_path)
33    add_files("nodes", ogn.nodes_path)
34    add_files("config", "config")
35    add_files("docs", ogn.docs_path)
36    add_files("data", "data")
37
38    -- Add the standard dependencies all OGN projects have. The second parameter is normally omitted for C++ nodes
39    -- as hot reload of C++ definitions is not yet supported.
40    add_ogn_dependencies(ogn)
41    
42    -- Begin OpenUSD
43    add_usd()
44    -- End OpenUSD
45
46    -- Link the directories required to make the extension definition complete
47    repo_build.prebuild_link {
48        { "docs", ext.target_dir.."/docs" },
49        { "data", ext.target_dir.."/data" },
50    }
51
52    -- This optional line adds support for CUDA (.cu) files in your project. Only include it if you are building nodes
53    -- that will run on the GPU and implement CUDA code to do so. Your deps/ directory should contain a file with a
54    -- cuda dependency that looks like the following to access the cuda library:
55    -- <dependency name="cuda" linkPath="../_build/target-deps/cuda">
56    --   <package name="cuda" version="11.8.0_520.61-d8963068-${platform}" platforms="linux-x86_64"/>
57    --   <package name="cuda" version="11.8.0_520.61-abe3d9d7-${platform}" platforms="linux-aarch64"/>
58    --   <package name="cuda" version="11.8.0_522.06-abe3d9d7-${platform}" platforms="windows-x86_64"/>
59    -- </dependency>
60    -- add_cuda_build_support()
61
62-- --------------------------------------------------------------------------------------------------------------------
63-- With the above copy/link operations this is what the source and build trees will look like
64--
65-- SOURCE                             BUILD
66-- omni.graph.template.cpp/        omni.graph.template.cpp/
67--   config/                            config@ -> SOURCE/config
68--   data/                              data@ -> SOURCE/data
69--   docs/                              docs@ -> SOURCE/docs
70--   nodes/                             ogn/ (generated by build)
71--   plugins/

Normally your nodes will have tests automatically generated for them, which will be in Python even though the nodes are in C++. By convention the installed Python files are structured in a directory tree that matches a namespace corresponding to the extension name, in this case omni/graph/template/cpp/, which corresponds to the extension name omni.graph.template.cpp. You’ll want to modify this to match your own extension’s name. Changing the first highlighted line is all you have to do to make that happen.

The Configuration

Every extension requires a config/extension.toml file with metadata describing the extension to the extension management system. Below is the annotated version of this file, where the highlighted lines are the ones you should change to match your own extension.

 1# Main extension description values
 2[package]
 3# The current extension version number - uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 4version = "2.20.0"
 5# The title of the extension that will appear in the extension window
 6title = "OmniGraph C++ Template"
 7# Longer description of the extension
 8description = "Templates for setting up an extension containing only C++ OmniGraph nodes."
 9# Authors/owners of the extension - usually an email by convention
10authors = ["NVIDIA <no-reply@nvidia.com>"]
11# Category under which the extension will be organized
12category = "Graph"
13# Location of the main README file describing the extension for extension developers
14readme = "docs/README.md"
15# Location of the main CHANGELOG file describing the modifications made to the extension during development
16changelog = "docs/CHANGELOG.md"
17# Location of the repository in which the extension's source can be found
18repository = "https://gitlab-master.nvidia.com/omniverse/kit-extensions/kit-omnigraph"
19# Keywords to help identify the extension when searching
20keywords = ["kit", "omnigraph", "nodes", "cpp", "c++"]
21# Image that shows up in the preview pane of the extension window
22preview_image = "data/preview.png"
23# Image that shows up in the navigation pane of the extension window - can be a .png, .jpg, or .svg
24icon = "data/icon.svg"
25# Specifying this ensures that the extension is always published for the matching version of the Kit SDK
26writeTarget.kit = true
27# Specify the minimum level for support
28support_level = "Sample"
29
30# Other extensions that need to load in order for this one to work
31[dependencies]
32"omni.graph.core" = {}       # For basic functionality
33"omni.graph.tools" = {} # For node generation
34
35# This extension has a compiled C++ project and so requires this declaration that it exists
36[[native.plugin]]
37path = "bin/*.plugin"
38recursive = false
39
40# Main pages published as part of documentation. (Only if you build and publish your documentation.)
41[documentation]
42pages = [
43    "docs/Overview.md",
44    "docs/CHANGELOG.md",
45]

Contained in this file are references to the icon file in data/icon.svg and the preview image in data/preview.png which control how your extension appears in the extension manager. You will want to customize those.

The Plugin Module

Every C++ extension requires some standard code setup to register and deregister the node types at the proper time. The minimum requirements for the Carbonite wrappers that implement this are containing in the file plugins/Module.cpp.

 1// SPDX-FileCopyrightText: Copyright (c) 2023-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 2// SPDX-License-Identifier: LicenseRef-NvidiaProprietary
 3//
 4// NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
 5// property and proprietary rights in and to this material, related
 6// documentation and any modifications thereto. Any use, reproduction,
 7// disclosure or distribution of this material and related documentation
 8// without an express license agreement from NVIDIA CORPORATION or
 9// its affiliates is strictly prohibited.
10
11// ==============================================================================================================
12//
13// This file contains mostly boilerplate code required to register the extension and the nodes in it.
14//
15// See the full documentation for OmniGraph Native Interfaces online at
16// https://docs.omniverse.nvidia.com/kit/docs/carbonite/latest/docs/OmniverseNativeInterfaces.html
17//
18// ==============================================================================================================
19
20#include <omni/core/ModuleInfo.h>
21#include <omni/core/Omni.h>
22#include <omni/graph/core/ogn/Registration.h>
23
24// These are the most common interfaces that will be used by nodes. Others that are used within the extension but
25// not registered here will issue a warning and can be added.
26OMNI_PLUGIN_IMPL_DEPS(omni::graph::core::IGraphRegistry, omni::fabric::IToken)
27
28OMNI_MODULE_GLOBALS("omni.graph.template.cpp.plugin", "OmniGraph Template With C++ Nodes");
29
30// This declaration is required in order for registration of C++ OmniGraph nodes to work
31DECLARE_OGN_NODES();
32
33namespace
34{
35void onStarted()
36{
37    // Macro required to register all of the C++ OmniGraph nodes in the extension
38    INITIALIZE_OGN_NODES();
39}
40
41bool onCanUnload()
42{
43    return true;
44}
45
46void onUnload()
47{
48    // Macro required to deregister all of the C++ OmniGraph nodes in the extension
49    RELEASE_OGN_NODES();
50}
51
52} // end of anonymous namespace
53
54// Hook up the above functions to the module to be called at the right times
55OMNI_MODULE_API omni::Result omniModuleGetExports(omni::ModuleExports* exports)
56{
57    OMNI_MODULE_SET_EXPORTS(exports);
58    OMNI_MODULE_ON_MODULE_STARTED(exports, onStarted);
59    OMNI_MODULE_ON_MODULE_CAN_UNLOAD(exports, onCanUnload);
60    OMNI_MODULE_ON_MODULE_UNLOAD(exports, onUnload);
61    OMNI_MODULE_GET_MODULE_DEPENDENCIES(exports, omniGetDependencies);
62
63    return omni::core::kResultSuccess;
64}

The first highlighted line shows where you customize the extension plugin name to match your own. The others indicate standard macros that set up the OmniGraph node type registration and deregistration process. Without these lines your node types will not be known to OmniGraph and will not be available in any of the editors.

Documentation

Everything in the docs/ subdirectory is considered documentation for the extension.

  • README.md The contents of this file appear in the extension manager window so you will want to customize it. The location of this file is configured in the extension.toml file as the readme value.

  • CHANGELOG.md It is good practice to keep track of changes to your extension so that users know what is available. The location of this file is configured in the extension.toml file as the changelog value, and as an entry in the [documentation] pages.

  • Overview.md This contains the main documentation page for the extension. It can stand alone or reference an arbitrarily complex set of files, images, and videos that document use of the extension. The toctree reference at the bottom of the file contains at least GeneratedNodeDocumentation/, which creates links to all of the documentation that is automatically generated for your nodes. The location of this file is configured in the extension.toml file in the [documentation] pages section.

  • directory.txt This file can be deleted as it is specific to these instructions.

The Node Type Definitions

You define a new node type using two files, examples of which are in the nodes/ subdirectory. Tailor the definition of your node types for your computations. Start with the OmniGraph User Guide for information on how to configure your own definitions.

That’s all there is to creating a simple C++ node type! You can now open your app, enable the new extension, and your sample node type will be available to use within OmniGraph.

OmniGraph Nodes In This Extension