HUSD Interface for passing Cryptomatte AOV information through Hydra. More...

#include <UT_HUSDExtraAOVResource.h>

Public Types
using	MapFunc = std::function< void *(int)>

using	UnmapFunc = std::function< void(int)>

Public Member Functions
SYS_FORCE_INLINE	UT_HUSDExtraAOVResource ()=default

SYS_FORCE_INLINE	UT_HUSDExtraAOVResource (MapFunc map, UnmapFunc unmap)

SYS_FORCE_INLINE	~UT_HUSDExtraAOVResource ()

SYS_FORCE_INLINE void	addPlane (const std::string &name, int hd_format)
	Convenience function to add an extra plane. More...

SYS_FORCE_INLINE void	addMetadata (const std::string &key, const std::string &value)
	Convenience method to add metadata. More...

SYS_FORCE_INLINE void	setMetadata (const std::map< std::string, std::string > &md)
	Convenience function to set the metadata map. More...

Public Attributes
MapFunc	myMap

UnmapFunc	myUnmap

std::vector< std::string >	myNames
	List of names for the affiliated AOV buffers. More...

std::vector< int >	myFormats

std::map< std::string, std::string >	myMetadata
	Dictionary of extra metadata for the AOV. More...

Detailed Description

HUSD Interface for passing Cryptomatte AOV information through Hydra.

Hydra has no facility for managing Cryptomatte AOVs. This class can be used to pass information between a render delegate and the HuskEngine.

This class is specifically created to not rely on any Houdini or USD classes, so it should be relatively save to include this header in any delegate's interface (see below for SYS_Inline.h)

The class is defined in UT so that it does not have to be part of the Houdini USD bridge and introduce any unwanted dependencies on the HUSD library.

If a render delegate wants to have a single AOV declare multiple child AOVs (extra/affiliated AOVs) in offline rendering in husk, the delegate can create a subclass for it's AOV buffers from HdRenderBuffer. The sub-class should implement the GetResource virtual and return VtValue storing a UT_HUSDExtraAOVResourcePtr.

This class lets a single AOV have multiple extra AOVs associated with it.

An example of this might be Cryptomatte AOVs where a single AOV is defined in the USD file, but then additional AOVs are created in the renderer to store additional data for cryptomatte layers. This interface isn't limited to cryptomatte, but can be used for any affiliated AOVs.

For example, a delegate might do something like

class AOVBuffer : public HdRenderBuffer
{
  // Code to map the buffer data for the extra AOV.  This is similar to the
  // Map() function, but returns the data buffer for the extra AOV.
  void  *mapExtra(int idx) { ... }
  // Unmap the extra AOV buffer
  void   unmapExtra(int idx) { ... }
  VtValue GetResource(bool) const {
    auto resource = std::make_shared<UT_HUSDExtraAOVResource>();
    resource->myMap = [=](int idx) { return this->mapExtra(idx); };
    resource->myUnmap = [=](int idx) { this->unmapExtra(idx); };
    for (int i = 0; i < numExtraPlanes; ++i)
        resource->addPlane(extraName[i], extraFormat[i]);
    for (auto &&meta : extraMetadata)
        resource->addMetadata(meta.first, meta.second);
    return VtValue(resource);
  }
  std::vector<std::string>              extraName;
  std::vector<HdFormat>                 extraFormat;
  std::map<std::string, std::string>    extraMetadata;
};

For example, in Karma, when an AOV sees a render var for cryptomatte:

        def RenderVar "MaterialChan" {
            ...
            bool driver:parameters:aov:cryptomatte = 1
            int driver:parameters:aov:cryptomatterank = 6
            string driver:parameters:aov:cryptomattesidecar = "manifest.txt"
//          token driver:parameters:aov:format = "color3f"

Karma will internally create additional buffers for "MaterialChan" AOV and provide the function to map the AOVs. The resource object would look something like:

resource->addPlane("MaterialChan00", HdFormatFloat32Vec4);
resource->addPlane("MaterialChan01", HdFormatFloat32Vec4);
resource->addPlane("MaterialChan02", HdFormatFloat32Vec4);
// The metadata must begin with "cryptomatte" and each key should be unique.
resource->addMetadata("cryptomatte/fea6747/conversion", "uint32_to_float32");
resource->addMetadata("cryptomatte/fea6747/manif_file", "manifest.txt");
resource->addMetadata("cryptomatte/fea6747/hash", "MurmurHash3_32");
resource->addMetadata("cryptomatte/fea6747/manifest",
               "{\"boxmat\":\"dce1d1e6\",\"spheremat\":\"710681f7\"}");

While it may be possible to store a UT_HUSDExtraAOVResourcePtr directly in the VtValue, the preferred method for passing this resource to husk is to store to return a VtValue holding a HdAovSettingsMap. This is due to symbol visibility and other issues.

The value in the map should be shared pointer stored behind an opaque shared void ptr. Houdini/husk will look for a shared_ptr<void> with the "extra_aov_resource" key and use a static cast to a UT_HUSDExtraAOVResourcePtr. The void pointer is only used to pass the shared ptr through the libraries. This mechanism allows the delegate to construct it's own struct, in its own codebase without relying on Houdini's libraries at all. For example:

VtValue
DelegateAOVBuffer::GetResource(bool) const {
    UT_HUSDExtraAOVResourcePtr extra_aovs = makeExtraAOVResource();
    HdAovSettingsMap  map;
    map.insert(TfToken("extra_aov_resource"),
         VtValue(std::static_pointer_cast<void>(extra_aovs)));
    return VtValue(map);
}
The current Karma implementation for Cryptomatte can be found at:
  https://github.com/sideeffects/HoudiniUsdBridge
in src/houdini/custom/RAY/BRAY_HdKarma/BRAY_HdAOVBuffer.C
The code that reads the resource can be found in:
  src/houdini/lib/H_USD/HUSD/HUSD_RenderBuffer.C
This is used by husk, and isn't particularly relevant for delegates.
The layout of this class will not change in the future.

Definition at line 145 of file UT_HUSDExtraAOVResource.h.

Member Typedef Documentation

using UT_HUSDExtraAOVResource::MapFunc = std::function<void *(int)>

Definition at line 147 of file UT_HUSDExtraAOVResource.h.

using UT_HUSDExtraAOVResource::UnmapFunc = std::function<void(int)>

Definition at line 148 of file UT_HUSDExtraAOVResource.h.

Constructor & Destructor Documentation

SYS_FORCE_INLINE UT_HUSDExtraAOVResource::UT_HUSDExtraAOVResource ( )

default

SYS_FORCE_INLINE UT_HUSDExtraAOVResource::UT_HUSDExtraAOVResource	(	MapFunc	map,
		UnmapFunc	unmap
	)

inline

Definition at line 151 of file UT_HUSDExtraAOVResource.h.

SYS_FORCE_INLINE UT_HUSDExtraAOVResource::~UT_HUSDExtraAOVResource ( )

inline

Definition at line 156 of file UT_HUSDExtraAOVResource.h.

Member Function Documentation

SYS_FORCE_INLINE void UT_HUSDExtraAOVResource::addMetadata	(	const std::string &	key,
		const std::string &	value
	)

inline

Convenience method to add metadata.

Definition at line 165 of file UT_HUSDExtraAOVResource.h.

SYS_FORCE_INLINE void UT_HUSDExtraAOVResource::addPlane	(	const std::string &	name,
		int	hd_format
	)

inline

Convenience function to add an extra plane.

Definition at line 159 of file UT_HUSDExtraAOVResource.h.

SYS_FORCE_INLINE void UT_HUSDExtraAOVResource::setMetadata ( const std::map< std::string, std::string > & md )

inline

Convenience function to set the metadata map.

Definition at line 171 of file UT_HUSDExtraAOVResource.h.

Member Data Documentation

std::vector<int> UT_HUSDExtraAOVResource::myFormats

List of the data formats for each of the affiliated AOV buffers. The integer stored should match the HdFormat enum. The length of the array should match the myNames array. It's stored as int to remove dependencies on the USD library. There may be issues if the HdFormats enum changes between versions.

Definition at line 193 of file UT_HUSDExtraAOVResource.h.

MapFunc UT_HUSDExtraAOVResource::myMap

Function to map the AOV buffer (similar to HdRenderBuffer::Map, but for an affiliated AOV).

Definition at line 179 of file UT_HUSDExtraAOVResource.h.

std::map<std::string, std::string> UT_HUSDExtraAOVResource::myMetadata

Dictionary of extra metadata for the AOV.

Definition at line 196 of file UT_HUSDExtraAOVResource.h.

std::vector<std::string> UT_HUSDExtraAOVResource::myNames

List of names for the affiliated AOV buffers.

Definition at line 186 of file UT_HUSDExtraAOVResource.h.

UnmapFunc UT_HUSDExtraAOVResource::myUnmap

Function to unmap the AOV buffer (similar to HdRenderBuffer::Unmap, but for an affiliated AOV).

Definition at line 183 of file UT_HUSDExtraAOVResource.h.

The documentation for this struct was generated from the following file:

UT/UT_HUSDExtraAOVResource.h

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation