UT_HUSDExtraAOVResource.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.
 *
 * NAME:        UT_HUSDExtraAOVResource.h (UT Library, C++)
 *
 * COMMENTS:
 *    Resource Data for to pass extra AOV buffers affiliated with a primary AOV
 *    in a HdRenderBuffer to husk.
 */

#ifndef __UT_HUSDExtraAOVResource__
#define __UT_HUSDExtraAOVResource__

#include <functional>
#include <map>
#include <memory>
#include <vector>
#include <string>

/// @brief 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 @c 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 @code
/// 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;
/// };
/// @endcode
///
/// For example, in Karma, when an AOV sees a render var for cryptomatte: @code
///     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"
/// @endcode
/// Karma will internally create additional buffers for "MaterialChan" AOV and
/// provide the function to map the AOVs.  The resource object would look
/// something like:
/// @code
///  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\"}");
/// @endcode
///
/// While it may be possible to store a UT_HUSDExtraAOVResourcePtr directly
/// in the VtValue, the preferred method for passing this resource to
/// @c 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 @c 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: @code
/// 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.
/// @endcode

// The only Houdini dependency is to get the SYS_FORCE_INLINE decorator
// This can be replaced if need be (see the source to SYS_Inline.h)
#include <SYS/SYS_Inline.h>

struct UT_HUSDExtraAOVResource
{
    using MapFunc = std::function<void *(int)>;
    using UnmapFunc = std::function<void(int)>;

    SYS_FORCE_INLINE UT_HUSDExtraAOVResource() = default;
    SYS_FORCE_INLINE UT_HUSDExtraAOVResource(MapFunc map, UnmapFunc unmap)
         : myMap(map)
         , myUnmap(unmap)
     {
     }
    SYS_FORCE_INLINE ~UT_HUSDExtraAOVResource() {}

    /// Convenience function to add an extra plane
    SYS_FORCE_INLINE void       addPlane(const std::string &name, int hd_format)
    {
        myNames.push_back(name);
        myFormats.push_back(hd_format);
    }
    /// Convenience method to add metadata
    SYS_FORCE_INLINE void       addMetadata(const std::string &key,
                                            const std::string &value)
    {
        myMetadata.insert({key, value});
    }
    /// Convenience function to set the metadata map
    SYS_FORCE_INLINE void       setMetadata(const std::map<std::string,
                                            std::string> &md)
    {
        myMetadata = md;
    }

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

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

    /// List of names for the affiliated AOV buffers
    std::vector<std::string>            myNames;

    /// 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 @c myNames array.
    /// It's stored as @c int to remove dependencies on the USD library.  There
    /// may be issues if the HdFormats enum changes between versions.
    std::vector<int>                    myFormats;

    /// Dictionary of extra metadata for the AOV
    std::map<std::string, std::string>  myMetadata;
};

using UT_HUSDExtraAOVResourcePtr = std::shared_ptr<UT_HUSDExtraAOVResource>;

#endif